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About This Book 



This book provides reference information for the classes, methods, functions, and macros of the SOMobjects Base Toolkit, which consists 
of the base (or core) capabilities in the System Object Model (SOM) of the SOMobjects Developer Toolkit. The base system is a rich 
subset of the full-capability SOMobjects Developer Toolkit. 

If you need guidance in using the capabilities of the base toolkit, refer to the System Object Mode/ Programming Guide . 

For purchasers of the full-capability SOMobjects systems, the SOMobjects Deve/oper Too/kit: Emitter Framework Guide and Reference 
contains documentation of the Emitter Framework of the SOMobjects Developer Toolkit. In addition, the SOMobjects Deveioper Too/kit: 
Co/iection C/asses Reference Manuai describes the collection classes and methods provided with the SOMobjects Developer Toolkit. 



SOM Kernel Reference 



somApply 



somApply - Syntax 



This function invokes an apply stub. Apply stubs are never invoked directly by SOM users. The somApply function must be used instead. 



SOMObject objPtr; 

somToken *retVal; 

somMethodDataPtr mdPtr; 
va_list args; 

boolean rc; 

rc = somApply (objPtr , retVal, mdPtr, args); 



somApply Parameter - objPtr 



objPtr (SOMObject) 

A pointer to the object on which the method procedure is to be invoked. 



somApply Parameter - retVal 



retVal (somToken *) 

A pointer to the memory region into which the result returned by the method procedure is to be copied. This pointer cannot be null 
(even in the case of method procedures whose returned result is void). 



somApply Parameter - mdPtr 



mdPtr (somMethodDataPtr) 

A pointer to the somMethodData structure that describes the method whose procedure is to be executed by the apply stub. 



somApply Parameter - args 



args (vajist) 

A vajist that contains the arguments for the method procedure. The first entry of the vajist must be obj'Ptr. Furthermore, all 
arguments on the vajist must appear in widened form, as defined by ANSI C. For example, a float must appear as a double, and a 
char and a short must appear as the int data type. The SOM API for vajist construction ensures this. 



somApply Parameter - rc 

rc (boolean) 



somApply - Parameters 



objPtr (SOMObject) 

A pointer to the object on which the method procedure is to be invoked. 



retVal (somToken *) 

A pointer to the memory region into which the result returned by the method procedure is to be copied. This pointer cannot be null 
(even in the case of method procedures whose returned result is void). 



mdPtr (somMethodDataPtr) 

A pointer to the somMethodData structure that describes the method whose procedure is to be executed by the apply stub. 



args (vajist) 

A vajist that contains the arguments for the method procedure. The first entry of the vajist must be obj'Ptr. Furthermore, all 
arguments on the vajist must appear in widened form, as defined by ANSI C. For example, a float must appear as a double, and a 
char and a short must appear as the int data type. The SOM API for vajist construction ensures this. 



rc (boolean) 




somApply - Remarks 



This function provides a single uniform interface through which it is possible to call any method procedure. The interface is based on the 
caller passing: the object to which the method procedure is to be applied; a return address for the method result; a somMethodDataPtr 
indicating the desired method procedure; and an ANSI standard vajist structure containing the method procedure arguments. Different 
method procedures expect different argument types and return different result types, so the purpose of this function is to select an app/y 
stub appropriate for the specific method involved, according to the supplied method data, and then call this apply stub. The apply stub 
removes the arguments from the vajist, calls the method procedure with these arguments, accepts the returned result, and then copies this 
result to the location pointed to by retVat. 

The method procedure used by the apply stub is determined by the content of the somMethodData structure pointed to by mc/Ptr. The 
class methods somGetMethodData and somGetNthMethodData are used to load a somMethodData structure. These methods resolve 
static method procedures based on the receiving class's instance method table. 

The SOM API requires that information necessary for selecting an apply stub be provided when a new method is registered with its 
introducing class (via the methods somAddStaticMethod or somAddDynamicMethod). This is required because SOM itself needs apply 
stubs when dispatch method resolution is used. C and C++ implementation bindings for SOM classes support this requirement, but SOM 
does not terminate execution if this requirement is not met by a class implementor. Thus, it is possible that there may be methods for which 
this function cannot select an appropriate apply stub. If an apply stub can be selected, then somApply performs as described above, and a 
TRUE value is returned; otherwise FALSE is returned. 



somApply - Related Information 



Data Structures 

• SOMObject (somobj.idl) 

• somMethodData (somapi.h) 

• somToken (sombtype.h) 

• somMethodPtr (sombtype.h) 

• vajist (stdarg.h) 



Methods 



somGetMethodData 
somGetNthMethodData 
somAddDynamicMethod (somcls.idl) 



somApply - Example Code 



#include <somcls.xh> 

#include <string.h> 

#include <stdarg.h> 
main ( ) 

{ 

somVaBuf vb; 
va_list args; 
string result; 

SOMClass *scOb j ; 
somMethodData md; 

somEnvironmentNew ( ) ; /* Init environment */ 

scObj = _SOMClass; /* The SOMClass object */ 

scOb j->somGetMethodData (somldFromString ( " somGetName" ) , 
vb = (somVaBuf ) somVaBuf_create (NULL, 0); 



&md) ; 




somVaBuf_add (vb, (char *)&scObj, tk_ulong) ; 
somVaBuf_get_valist (vb, &args); 

somApply (scOb j , (somToken*) sresult, Smd, args); 
SOM_Assert (! strcmp (result, "SOMClass"), SOM_Fatal) 
/* result is "SOMClass" */ 



somApply - 


Topics 
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somBeginPersistentlds 
somBeginPersistentlds - Syntax 

This functions tells SOM to begin a "persistent ID interval." 

somBeginPersistentlds () ; 

somBeginPersistentlds Parameter - rc 

rc 



somBeginPersistentlds - Parameters 



rc 



somBeginPersistentlds - Remarks 



This function informs the SOM ID manager that strings for any new SOM IDs that are registered will not be freed or modified. This allows the 
ID manager to use a pointer to the string in the unregistered ID as the master copy of the ID's string, rather than making a copy of the string. 
This makes ID handling more efficient. 



somBeginPersistentlds - Related Information 



Functions 



• somCheckld 

• somRegisterld 

• somldFromString 

• somStringFromld 

• somComparelds 

• somTotalReglds 

• somUniqueKey 

• somSetExpectedlds 

• somEndPersistentlds 



somBeginPersistentlds - Example Code 



#include <som.h> 

/* This is the way to create somlds efficiently */ 
static string idlName = "whoami"; 
static somld somId_idl = &idlName; 

/* 

somId_idl will be registered the first time it is used 
in an operation that takes a somld, or it can be explicitly 
registered using somCheckld. 

*/ 

main ( ) 

{ 

somld idl, id2; 

string id2Name = "whereami"; 

somEnvironmentNew ( ) ; 
somBeginPersistentlds () ; 

idl = somCheckld (somId_idl ) ; /* registers the id as persistent */ 
somEndPersistentlds () ; 

id2 = somldFromString (id2Name) ; /* registers the id */ 

SOM_Assert (! strcmp ( "whoami" , somStringFromld (idl ) ) , SOM_Fatal) ; 
SOM_Assert (! strcmp ( "whereami" , somStringFromld (id2 ) ) , SOM_Fatal) ; 

idlName = "it does matter"; /* because it is persistent */ 
id2Name = "it doesn't matter"; /* because it is not persistent */ 

SOM_Assert (strcmp ( "whoami" , somStringFromld (idl ) ) , SOM_Fatal) ; 




/* The idl string has changed */ 

SOM_Assert ( ! strcmp ( "whereami" , somStringFromld (id2 ) ) , SOM_Fatal) ; 
/* the id2 string has not */ 



somBeginPersistentlds - Topics 
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somBuildClass 



somBuildClass - Syntax 



This function automates the process of building a new SOM class object. 



unsigned long inheritVars; 

somStaticClassInfoPtr sciPtr; 
long ma jorVersion; 

long minorVersion; 

SOMClass rc; 

rc = somBuildClass (inheritVars, sciPtr, ma jorVersion, 
minorVersion) ; 



somBuildClass Parameter - inheritVars 



inheritVars (unsigned long) 

A bit mask that determines inheritance from parent classes. A mask containing all ones is an appropriate default. 



somBuildClass Parameter - sciPtr 



sciPtr (somStaticClassInfoPtr) 

A pointer to a structure holding static class information. 



somBuildClass Parameter - majorVersion 



majorVersion (long) 

The major version number for the class. 



somBuildClass Parameter - minorVersion 



minorVersion (long) 

The minor version number for the class. 



somBuildClass Parameter - rc 



rc (SOMCIass) 

A pointer to a class object. 



somBuildClass - Parameters 



inheritVars (unsigned long) 

A bit mask that determines inheritance from parent classes. A mask containing all ones is an appropriate default. 

sciPtr (somStaticClassInfoPtr) 

A pointer to a structure holding static class information. 

majorVersion (long) 

The major version number for the class. 

minorVersion (long) 

The minor version number for the class. 

rc (SOMCIass) 

A pointer to a class object. 



somBuildClass - Remarks 




This function accepts declarative information defining a new class that is be built, and performs the activities required to build and register a 
correctly functioning class object. The C and C++ implementation bindings use this function to create class objects. 



somBuildClass - Related Information 



Data Structures 

• somStaticClassInfo (somapi.h) 



somBuildClass - Example Code 



See any . ih or .xih implementation binding file for 
details on construction of the required data 
structures . 



somBuildClass - Topics 
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somCheckld 



somCheckld - Syntax 



This function registers a som ID. 



somld id; 

somld rc; 

rc = somCheckld (id) ; 



somCheckld Parameter - id 



id (somld) 

The somld to be registered. 



somCheckld Parameter - rc 



rc (somld) 



The registered somld. 



somCheckld - Parameters 



id (somld) 

The somld to be registered, 
rc (somld) 

The registered somld. 



somCheckld - Remarks 



This function registers a SOM ID and converts it into an internal representation. The input SOM ID is returned. It the ID is already registered, 
this function has no effect. 



somCheckld - Related Information 



Data Structures 



somld (sombtype.h) 



Methods 



• somRegisterld 

• somFromString 

• somStringFromld 

• comComparelds 

• somTotalReglds 

• somSetExpectedlds 

• somUniqueKey 

• somBeginPersistentlds 

• somEndPersistentlds 



somCheckld - Example Code 



See function somBeginPersistentlds () . 



somCheckld - Topics 
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somClassResolve 



somClassResolve - Syntax 



This function obtains a pointer to the procedure that implements a static method for instances of a particular SOM class. 



SOMClass els; 

somMToken mToken; 

somMethodPtr rc; 



rc = somClassResolve (els, mToken); 



somClassResolve Parameter - els 



els (SOMCIass) 

A pointer to the class object whose instance method procedure is required. 



somClassResolve Parameter - mToken 



mToken (somMToken) 

The method token for the method to be resolved. The SOM API requires that if the class "XYZ" introduces the static method "foo", 
then the method token for "foo" is found in the class data structure for "XYZ" (called XYZCIassData) in the structure member named 
"foo" (i.e., at XYZCIassData.foo). Method tokens can also be obtained using the somGetMethodToken method. A pointer to the 
class object whose instance method procedure is required. 



somClassResolve Parameter - rc 



rc (somMethodPtr) 



A pointer to the somMethodProc (procedure) that implements the specified method for the specified class of SOM object. 



somClassResolve - Parameters 



els (SOMCIass) 

A pointer to the class object whose instance method procedure is required. 



mToken (somMToken) 

The method token for the method to be resolved. The SOM API requires that if the class "XYZ" introduces the static method "foo", 
then the method token for "foo" is found in the class data structure for "XYZ" (called XYZCIassData) in the structure member named 
"foo" (i.e., at XYZCIassData.foo). Method tokens can also be obtained using the somGetMethodToken method. A pointer to the 
class object whose instance method procedure is required. 



rc (somMethodPtr) 



A pointer to the somMethodProc (procedure) that implements the specified method for the specified class of SOM object. 



somClassResolve - Remarks 




This function is used to obtain a pointer to the procedure that implements the specified method for instances of the specified SOM class. 
The returned procedure pointer can then be used to invoke the method. The somClassResolve function is used to support "casted" method 
calls, in which a method is resolved with respect to a specified class rather than the class of which an object is a direct instance. The 
somClassResolve function can only be used to obtain a method procedure for a static method (a method declared in an IDL specification 
for a class); dynamic methods do not have method tokens. 

The SOM language usage bindings for C and C++ do not support casted method calls, so this function must be used directly to achieve this 
functionality. Whenever using SOM method procedure pointers, it is necessary to indicate the use of system linkage to the compiler. The 
way this is done depends on the compiler and the system being used. However, C and C++ usage bindings provide an appropriate typedef 
for this purpose. The name of the typedef is based on the name of the class that introduces the method, as illustrated in the example below. 



somClassResolve - Related Information 



Data Structures 

• somMethodPtr (sombtype.h) 

• SOMCIass (somcls.idl) 

• somMToken (somapi.h) 



Functions 



somResolveByName 
somParentResolve 
somParentNumResolve 
som Resolve 



Methods 

• somDispatch 

• somClassDispatch 

• somFindMethod 

• somFindMethodOk 

• somGetMethodToken 

Macros 



SOMResolve 

SOMResolveNoCheck 



somClassResolve - Example Code 



// SOM IDL for class A and class B 
#include <somobj.idl> 
module scrExample { 

interface A : SOMObject { void foo(); implementation 
{ callstyle=oidl; } ; } ; 

interface B : A { implementation { foo: override;};}; 

} ; 



// Example C++ program to implement and test module scrExample 
#def ine SOM_Module_screxample_Source 
#include <scrExample . xih> 

#include <stdio.h> 

SOM_Scope void SOMLINK scrExample_Af oo ( scrExample_A *somSelf ) ; 
{ print f ( " l\n" ) ; } 

SOM_Scope void SOMLINK scrExample_Bf oo ( scrExample_B *somSelf ) ; 
{ print f ( "2\n" ) ; } 




main ( ) 

{ 

scrExample_B *objPtr = new scrExample_B; 

// This prints 2 
ob jPtr->foo ( ) ; 

// This prints 1 

( (somTD_scrExample_A_foo) /* A necessary method procedure cast */ 
somClassResolve ( 

,_scrExample_A, // the A class object 
scrExample_AClassData . foo) // the foo method token 
) /* end of method procedure expression */ 

(objPtr) ; /* method arguments */ 

// This prints 2 

( (somTD_scrExample_A_foo) /* A necessary method procedure cast */ 
somClassResolve ( 

,_scrExample_B, // the B class object 
scrExample_AClassData . foo) // the foo method token 
) /* end of method procedure expression */ 

(objPtr) ; /* method arguments */ 



somClassResolve - Topics 
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somComparelds 



somComparelds - Syntax 



This function determines whether two SOM IDs represent the same string. 



somld idl; 
somld id2; 
int rc; 

rc = somComparelds (idl , id2); 



somComparelds Parameter - idl 



idl (somld) 

The first SOM ID to be compared. 



somComparelds Parameter - id2 



id2 (somld) 

The second SOM ID to be compared. 



somComparelds Parameter - rc 

rc (int) 

1 Returns 1 if the two input IDs represent strings that are equal. 

0 Returns 0 if the two input IDs represent strings that are not equal 



somComparelds - Parameters 



idl (somld) 

The first SOM ID to be compared. 
id2 (somld) 

The second SOM ID to be compared. 



rc (int) 



1 

0 



Returns 1 if the two input IDs represent strings that are equal. 
Returns 0 if the two input IDs represent strings that are not equal 



somComparelds - Remarks 



This function returns 1 if the two input IDs represent strings that are equal; otherwise, it returns 0. 



somComparelds - Related Information 




Data Structures 



somld (sombtype.h) 



Functions 



• somCheckld 

• somRegisterld 

• somldFromString 

• somStringFromld 

• somTotalReglds 

• somSetExpectedlds 

• somllniqueKey 

• somBeginPersistentlds 

• somEndPersistentlds 



somComparelds - Example Code 



#include <som.h> 
main ( ) 

{ 

somld idl, id2, id3; 
somEnvironmentNew ( ) ; 

idl = somldFromString ( "this" ) ; 

id2 = somldFromString ( "that ") ; 
id3 = somldFromString ( "this" ) ; 

SOM_Test (somComparelds (idl, id3) ) ; 
SOM_Test ( ! somComparelds (idl, id2) ) ; 



somComparelds - Topics 
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somDataResolve 



somDataResolve - Syntax 



This function accesses instance data within an object. 



SOMObject obj; 

somDToken dToken; 

somToken rc; 

rc = somDataResolve (obj , dToken); 



somDataResolve Parameter - obj 



obj (SOMObject) 

A pointer to the object whose instance data is required. 



somDataResolve Parameter - dToken 



dToken (somDToken) 

A data token for the required instance data. The SOM API specifies that the data token for accessing the instance data introduced by 
a class is found in the instanceDataToken component of the auxiliary class data structure for that class. The example below 
illustrates this. 



somDataResolve Parameter - rc 



rc (somToken) 



A somToken (that is, a pointer) that points to the data in obj identified by the dToken. If obj does not contain the requested data 
identified by c/Token , somDataResolve generates a runtime error. 



somDataResolve - Parameters 



obj (SOMObject) 

A pointer to the object whose instance data is required. 



dToken (somDToken) 

A data token for the required instance data. The SOM API specifies that the data token for accessing the instance data introduced by 
a class is found in the instanceDataToken component of the auxiliary class data structure for that class. The example below 
illustrates this. 



rc (somToken) 



A somToken (that is, a pointer) that points to the data in obj identified by the dToken. If obj does not contain the requested data 
identified by c/Token , somDataResolve generates a runtime error. 



somDataResolve - Remarks 

The somDataResolve function is used to access instance data within an object. This function is of use primarily to class implementors 
(rather than class clients) who are not using the SOM C or C++ language bindings. 

For C or C++ programmers with access to the C or C++ implementation bindings for a class, instance data can be accessed using the 
GetData macro (which expands to a usage of somDataResolve). 



somDataResolve ■ 


- Related Information 


Data Structures 

• somToken (sombtype.h) 

• SOMObject (somobj.idl) 

• somDToken (somapi.h) 





somDataResolve ■ 


- Example Code 



The following C/C++ expression evaluates to the address of the instance data introduced by class "XYZ” within the object "obj". This 
assumes that obj points to an instance of "XYZ" or a subclass of "XYZ". 

#include <som.h> 

somDataResolve (obj , XYZCClassData . instanceDataToken) ; 



somDataResolve ■ 


- Topics 
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somDataResolveChk 



somDataResolveChk - Syntax 



This function accesses instance data within an object. 



SOMObject obj; 

somDToken dToken; 

somToken rc; 

rc = somDataResolveChk (obj , dToken); 



somDataResolveChk Parameter - obj 



obj (SOMObject) 

A pointer to the object whose instance data is required. 



somDataResolveChk Parameter - dToken 



dToken (somDToken) 

A data token for the required instance data. The SOM API specifies that the data token for accessing the instance data introduced by 
a class is found in the instanceDataToken component of the auxiliary class data structure for that class. The example below 
illustrates this. 



somDataResolveChk Parameter - rc 



rc (somToken) 



A somToken (that is, a pointer) that points to the data in obj identified by the dToken. If obj does not contain the requested data 
identified by dToken , somDataResolveChk returns NULL. 



somDataResolveChk - Parameters 



obj (SOMObject) 

A pointer to the object whose instance data is required. 



dToken (somDToken) 

A data token for the required instance data. The SOM API specifies that the data token for accessing the instance data introduced by 
a class is found in the instanceDataToken component of the auxiliary class data structure for that class. The example below 
illustrates this. 



rc (somToken) 



A somToken (that is, a pointer) that points to the data in obj identified by the dToken. If obj does not contain the requested data 
identified by c/Token , somDataResolveChk returns NULL. 



somDataResolveChk - Remarks 



The somDataResolveChk function is used to access instance data within an object. This function is of use primarily to class implementors 
(rather than class clients) who are not using the SOM C or C++ language bindings. 

For C or C++ programmers with access to the C or C++ implementation bindings for a class, instance data can be accessed using the 
GetData macro (which expands to a usage of somDataResolve). 



somDataResolveChk - Related Information 



Data Structures 

• somToken (sombtype.h) 

• SOMObject (somobj.idl) 

• somDToken (somapi.h) 



somDataResolveChk - Example Code 



The following C/C++ expression evaluates to the address of the instance data introduced by class "XYZ" within the object "obj". This 
assumes that obj points to an instance of "XYZ" or a subclass of "XYZ". 

#include <som.h> 

somDataResolveChk (ob j , XYZCClassData . instanceDataToken) ; 



somDataResolveChk - Topics 
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somEndPersistentlds 



somEndPersistentlds - Syntax 



This function tells SOM to end a "persistent ID interval." 



somEndPersistentlds () ; 



somEndPersistentlds Parameter - rc 



somEndPersistentlds - Parameters 



somEndPersistentlds - Remarks 



This function informs the SOM ID manager that strings for any new SOM IDs that are registered might be freed or modified by the client 
program. Thus, the ID manager must make a copy of the strings. 



somEndPersistentlds - Related Information 



Methods 



• somCheckld 

• somRegisterld 

• somldFromString 

• somStringFromld 

• somComparelds 

• somTotalReglds 

• somllniqueKey 

• someSetExpectedlds 

• somBeginPersistentlds 



somEndPersistentlds - Example Code 



See function somBeginPersistentlds. 



somEndPersistentlds - Topics 
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somEnvironmentEnd 



somEnvironmentEnd - Syntax 



This function provides general cleanup for applications. 



somEnvironmentEnd ( ) ; 



somEnvironmentEnd Parameter - rc 



rc 



somEnvironmentEnd ■ 


- Parameters 



somEnvironmentEnd ■ 


- Remarks 



This function is a general cleanup function that must be called by all Windows applications before exiting. AIX and OS/2 programs may also 
invoke this function, but it is not required on these systems because all necessary SOM cleanup is performed by the operating system 
during program termination. 

A convenience macro, SOM_MainProgram, which usually appears at the beginning of each application, adds this function to the "atexit" list. 
If the "atexit" mechanism does not work reliably with your compiler, or if you know that your program bypasses the normal program 
termination sequence, you should insert an explicit call to this function at the point where your main program exits. (All main programs for 
Windows must begin either with the SOM_MainProgram macro or with a call to the somMainProgram function.) 



somEnvironmentEnd ■ 


- Related Information 


Macros 

• SOMMainProgram 





somEnvironmentEnd ■ 


- Topics 
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somEnvironmentNew 



somEnvironmentNew - Syntax 



This function initializes the SOM runtime environment. 



SOMClassMgr rc; 

rc = somEnvironmentNew () ; 



somEnvironmentNew Parameter - rc 



rc (SOMClassMgr) 



A pointer to the single class manager object active at run time. This class manager can be referred by the global variable 
SOMC/assMgrOb/ect . 



somEnvironmentNew - Parameters 



rc (SOMClassMgr) 



A pointer to the single class manager object active at run time. This class manager can be referred by the global variable 
SOMC/assMgrOb/ect . 



somEnvironmentNew - Remarks 



This function creates the four primitive SOM objects ( SOMObject, SOMC/ass, SOMC/assMg\, and SOMC/assMgrOb/ect ) and initializes 
global variables used by the SOM run-time environment. This function must be called before using any other SOM functions or methods 
(with the exception of somSetExpectedlds). If the SOM run-time environment has already been initialized, calling this function has no 
harmful effect. 

Although this function must be called before using other SOM functions or methods, it needn't always be called explicitly, because the New 
macros, the Renew macros, the new operator, and the NewClass procedures defined by the SOM C and C++ language bindings call 

somEnvironmentNew if needed. 



somEnvironmentNew - Related Information 



Functions 



somExceptionld 
somException Value 
somSetException 
somGetGlobalEnvironment 



somEnvironmentNew - Example Code 



somEnvironmentNew ( ) ; 



somEnvironmentNew - Topics 



Select an item: 
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Parameters 
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Remarks 
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somExceptionFree 



somExceptionFree - Syntax 



This function frees the memory held by the exception structure within an Environment structure. 



Environment *env; 

somExceptionFree (env) ; 



somExceptionFree Parameter - env 



env (Environment *) 

A pointer to the Environment whose exception information is to be freed. 



somExceptionFree Parameter - rc 



somExceptionFree - Parameters 



env (Environment *) 

A pointer to the Environment whose exception information is to be freed. 



rc 



somExceptionFree - Remarks 



This function frees the memory held by the exception structure within an Environment structure. 



somExceptionFree - Related Information 



Data Structures 

• Environment (somcorba.h) 



Functions 



• somExceptionld 

• somExceptionValue 

• somSetException 

• somGetGlobalEnvironment 

• somdExceptionFree (DSOM function) 



somExceptionFree - Example Code 




See function somSetException . 



somExceptionFree - Topics 



Select an item: 
Syntax 
Parameters 
Returns 
Remarks 
Example Code 
Related Information 
Glossary 



somExceptionld 



somExceptionld - Syntax 



This function gets the name of the exception contained in an Environment structure. 



Environment *env; 

string rc; 

rc = somExceptionld (env) ; 



somExceptionld Parameter - env 



env (Environment *) 

A pointer to an Environment structure containing an exception. 



somExceptionld Parameter - rc 



rc (string) 



string 



Returns the name of the exception contained in the specified Environment structure, as a string. 



somExceptionld - Parameters 



env (Environment *) 

A pointer to an Environment structure containing an exception, 
rc (string) 



string 



Returns the name of the exception contained in the specified Environment structure, as a string. 



somExceptionld - Remarks 



This function returns the name of the exception contained in the specified Environment structure. 



somExceptionld - Related Information 



Data Structures 

• string (somcorba.h) 

• Environment (somcorba.h) 



Functions 



somExceptionValue 

somExceptionFree 

somSetException 

somGetGlobalEnvironment 



somExceptionld - Example Code 



See function somSetException. 




somExceptionld - Topics 
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somExceptionValue 



somExceptionValue - Syntax 



This function gets the value of the exception contained in an Environment structure. 



Environment *env; 

somToken rc; 

rc = somExceptionValue (env) ; 



somExceptionValue Parameter - env 



env (Environment *) 

A pointer to an Environment structure containing an exception. 



somExceptionValue Parameter - rc 



rc (somToken) 

Returns a pointer to the value of the exception contained in the specified Environment structure. 



somExceptionValue - Parameters 



env (Environment *) 

A pointer to an Environment structure containing an exception, 
rc (somToken) 

Returns a pointer to the value of the exception contained in the specified Environment structure. 



somExceptionValue - Remarks 



This function returns the value of the exception contained in the specified Environment structure. 



somExceptionValue - Related Information 



Data Structures 

• somToken (sombtype.h) 

• Environment (somcorba.h) 



Functions 



• somExceptionld 

• somExceptionFree 

• somSetException 

• somGetGlobalEnvironment 

• somSetGlobalEnvironment 



somExceptionValue - Example Code 



See function somSetException. 



somExceptionValue - Topics 
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somGetGlobalEnvironment 



somGetGlobalEnvironment - Syntax 



This function returns a pointer to the current global Environment structure. 

Environment *rc; 

rc = somGetGlobalEnvironment () ; 



somGetGlobalEnvironment Parameter - rc 



rc (Environment *) 



A pointer to the current global Environment structure. 



somGetGlobalEnvironment - Parameters 



rc (Environment *) 



A pointer to the current global Environment structure. 



somGetGlobalEnvironment - Remarks 

This function returns a pointer to the current global Environment structure. This structure can be passed to methods that require an 
(Environment *) argument. The caller can determine if the called method has raised an exception by testing whether 

ev->exception ._ma jor != NO_EXCEPTION 



If an exception has been raised, the caller can retrieve the name and value of the exception using the somExceptionld and 
somExceptionValue methods. 



somGetGlobalEnvironment - Related Information 



Data Structures 

• Environment (somcorba.h) 



Functions 



somExceptionld 
somException Value 
somExceptionFree 
somSetException 



somGetGlobalEnvironment - Example Code 



See function somSetException. 



somGetGlobalEnvironment - Topics 
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Parameters 
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Remarks 
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somldFromString 



somldFromString - Syntax 



This function returns the SOM ID corresponding to a given text string. 



string 

somld 



aString; 

rc; 



rc = somldFromString (aString) ; 



somldFromString Parameter - aString 



aString (string) 

The string to be converted to a SOM ID. 



somldFromString Parameter - rc 



rc (somld) 



Returns the SOM ID corresponding to the given text string. 



somldFromString - Parameters 



aString (string) 

The string to be converted to a SOM ID. 
rc (somld) 



Returns the SOM ID corresponding to the given text string. 



somldFromString - Remarks 



This function returns the SOM ID that corresponds to a given text string. 

Ownership of the somld returned by this function passes to the caller, which has the responsibility to subsequently free the somld using 
SOMFree. 



somldFromString - Related Information 



Data Structures 




somld (sombtype.h) 
string (somcorba.h) 



Functions 



• somCheckld 

• somRegisterld 

• somStringFromld 

• somComparelds 

• somTotalReglds 

• somSetExpectedlds 

• somUniqueKey 

• somBeginPersistentlds 

• somEndPersistentlds 



somldFromString - Example Code 



See function somBeginPersistentlds. 



somldFromString - Topics 
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somlsObj 



somlsObj - Syntax 



This function is a failsafe routine to determine whether a pointer references a valid SOM object. 



somToken memPtr; 

boolean rc; 

rc = somlsObj (memPtr) ; 



somlsObj Parameter - memPtr 



memPtr (somToken) 

A somToken (a pointer) to be checked. 



somlsObj Parameter - rc 

rc (boolean) 

1 Returns 1 if obj is a pointer to a valid SOM object. 

0 Returns 0 if obj is not a pointer to an valid SOM object. 



somlsObj - Parameters 

memPtr (somToken) 

A somToken (a pointer) to be checked. 

rc (boolean) 



1 Returns 1 if obj is a pointer to a valid SOM object. 

0 Returns 0 if obj is not a pointer to an valid SOM object. 



somlsObj - Remarks 



This function returns 1 if its argument is a pointer to a valid SOM object, or returns 0 otherwise. The function handles address faults, and 
does extensive consistency checking to guarantee a correct result. 



somlsObj - Related Information 



Data Structures 

• boolean (somcorba.h) 

• somToken (sombtype.h) 




somlsObj - Example Code 



#include <stdio.h> 
#include <som.xh> 



void example (void *memPtr) 

{ 



if ( ! somlsOb j (memPtr ) ) 
print f ( "memPtr is not 
else 

print f ( "memPtr points 
( (SOMObject * 



a valid SOM ob ject . \n" ) ; 

to an object of class %s\n", 
) memPtr) ->somGetClassName ( ) ) ; 



somlsObj - Topics 



Select an item: 
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somLPrintf 



somLPrintf - Syntax 



This function prints a formatted string in the manner of the C printf function, at the specified indentation level. 



long level; 

string fmt; 

long rc; 

rc = somLPrintf (level, fmt,* • •); 



The values to be substituted 
into the format string. 



somLPrintf Parameter - level 



level (long) 

The level at which output is to be placed. 



somLPrintf Parameter - fmt 



fmt (string) 

The format string to be output. 



somLPrintf Parameter - rc 



rc (long) 

Returns the number of characters written. 



somLPrintf - Parameters 



level (long) 

The level at which output is to be placed, 
fmt (string) 

The format string to be output, 
rc (long) 

Returns the number of characters written. 



somLPrintf - Remarks 



This function prints a formatted string using SOMOutCharRoutine, in the same manner as the C printf function. The implementation of 
SOMOutCharRoutine determines the destination of the output, while the C printf function is always directed to stdout. (The default output 
destination for SOMOutCharRoutine is stdout also, but this can be modified by the user.) The output is prefixed at the indicated level, by 
preceding it with 2*level spaces. 




somLPrintf - Related Information 



Data Structures 

• string (somcorba.h) 



Functions 



somVprintf 

somPrefixLevel 

somPrintf 

SOMOutCharRoutine 



somLPrintf - Example Code 



#include <somobj.h> 

somLPrintf (5, "The class name is %s.\n", _somGetClassName (ob j ) ) ; 



somLPrintf - Topics 



Select an item: 
Syntax 
Parameters 
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so m Main Program 



somMainProgram - Syntax 



This function performs SOM initialization on behalf of a new program. 



SOMClassMgr *rc; 

rc = somMainProgram () ; 



so m Main Program Parameter - rc 



rc (SOMCIassMgr *) 

A pointer to the SOMCIassMgr object. 



somMainProgram - Parameters 



rc (SOMCIassMgr *) 

A pointer to the SOMCIassMgr object. 



somMainProgram - Remarks 



This function informs SOM about the beginning of a new thread of execution (called a task on Windows). The SOM Kernel then performs 
any needed initialization, including the deferred execution of the SOMInitModule functions found in statically-loaded class libraries. This 
function must appear near the beginning of all Windows main programs, and may also be used in AIX or OS/2 programs. When used, it 
supersedes any need to call the somEnvironmentNew function. 

A convenience macro, SOM_MainProgram, which combines the execution of this function with the scheduling of the somEnvironmentEnd 
function during normal program termination, is available for C and C++ programmers. 



somMainProgram - Related Information 



Functions 



somEnvironmentNew 

somEnvironmentEnd 



Macros 



SOMMainProgram 

SOMCIassLibrary 



somMainProgram - Topics 



Select an item: 

Syntax 

Parameters 



Returns 

Remarks 

Related Information 
Glossary 



somParentNumResolve 



somParentNumResolve - Syntax 



This function obtains a pointer to a procedure that implements a method, given a list of method tables. 



somMethodTabs 

int 

somMToken 

somMethodPtr 



parentMtab; 

parentNum; 

mToken; 

rc; 



rc = _somParentNumResolve (parentMtab, parentNum, 
mToken) ; 



somParentNumResolve Parameter - parentMtab 



parentMtab (somMethodTabs) 

A list of method tables for the parents of the class being implemented. The SOM API specifies that the list of parent method tables for 
a given class be stored in the auxiliary class data structure of the class, in the parentMtab component. Thus, for the class "XYZ", the 
parent method table list is found in location XYZCC/assData. parentMtab. Parent method table lists are available from class objects 
via the method call somGetPCIsMtabs. 



somParentNumResolve Parameter - parentNum 



parentNum (int) 

The position of the parent for which the method is to be resolved. The order of a class's parents is determined by the order in which 
they are specified in the interface statement for the class. (The first parent is number 1 .) 



somParentNumResolve Parameter - mToken 



mToken (somMToken) 

The method token for the method to be resolved. The SOM API requires that if the class "XYZ" introduces the static method "too", 
then the method token for "foo" is found in the class data structure for "XYZ" (called XYZCIassData) in the structure member named 
"foo" (i.e., at XYZCIassData.foo). Method tokens can also be obtained using the somGetMethodToken method. 



somParentNumResolve Parameter - rc 



rc (somMethodPtr) 



A pointer to a somMethodProc (procedure) that implements the specified method, selected from the specified method table. 



somParentNumResolve - Parameters 



parentMtab (somMethodTabs) 

A list of method tables for the parents of the class being implemented. The SOM API specifies that the list of parent method tables for 
a given class be stored in the auxiliary class data structure of the class, in the parentMtab component. Thus, for the class "XYZ", the 
parent method table list is found in location XYZCC/assData. parentMtab. Parent method table lists are available from class objects 
via the method call somGetPCIsMtabs. 

parentNum (int) 

The position of the parent for which the method is to be resolved. The order of a class's parents is determined by the order in which 
they are specified in the interface statement for the class. (The first parent is number 1 .) 

mToken (somMToken) 

The method token for the method to be resolved. The SOM API requires that if the class "XYZ" introduces the static method "foo", 
then the method token for “foo" is found in the class data structure for "XYZ" (called XYZCIassData) in the structure member named 
"foo" (i.e., at XYZCIassData.foo). Method tokens can also be obtained using the somGetMethodToken method. 

rc (somMethodPtr) 



A pointer to a somMethodProc (procedure) that implements the specified method, selected from the specified method table. 



somParentNumResolve - Remarks 



This function is used to make parent method calls by the C and C++ language implementation bindings. The somParentNumResolve 
function returns a pointer to a procedure for performing the specified method. This pointer is selected from the specified method table, which 
is intended to be the method table corresponding to a parent class. 

For C and C++ programmers, the implementation bindings for SOM classes provide convenient macros for making parent method calls (the 
"parent_" macros). 



somParentNumResolve - Related Information 



Data Structures 




Data Structures 
somMethodPtr(sombtype.h) 
somMethodTabs(somapi.h) 
somMToken (somapi.h) 



Functions 



somResolveByName 
som Resolve 
somParentNumResolve 
somClassResolve 



Methods 

• somGetPCIsMtab 

• somGetPCIsMtabs 

• somGetMethodToken 

Macros 



SOMParentNumResolve 

SOMResolve 

SOMResolveNoCheck 



somParentNumResolve - Example Code 



// SOM IDL for class A and class B 
#include <somobj.h> 
module spnrExample { 

interface A : SOMObject { void foo(); 
implementation { callstyle=oidl; }; }; 

interface B : A { implementation { foo: override; }; }; 

} ; 



// Example C++ program to implement and test module scrExample 
#def ine SOM_Module_spnrexample_Source 
#include <spnrExample . xih> 

#include <stdio.h> 

SOM_Scope void SOMLINK spnrExample_Af oo ( spnrExample_A *somSelf ) ; 

{ print f ("l\n") ; } 

SOM_Scope void SOMLINK spnrExample_Bf oo ( spnrExample_B *somSelf ) ; 

{ print f ( "2\n" ) ; } 

main ( ) 

{ 

spnrExample_B *objPtr = new spnrExample_B; 

// This prints 2 
ob jPtr->foo ( ) ; 

// This prints 1 

( (somTD_spnrExample_A_foo) 

/* This method procedure expression cast is necessary */ 
somParentNumResolve ( 

, ob jPtr->somGetClass ( ) ->somGetPClsMtabs ( ) , 

"i" 

spnrExample_AClassData . f oo) // the foo method token 
) /* end of method procedure expression */ 

(objPtr) ; /* method arguments */ 




somParentNumResolve - Topics 
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somParentResolve 



somParentResolve - Syntax 



This function obtains a pointer to a procedure that implements a method, given a list of method tables. Obsolete but still supported. 



somMethodTabs 

somToken 

somMethodPtr 



parentMtab; 

mToken; 

rc; 



rc = somParentResolve (parentMtab, mToken), 



somParentResolve Parameter - parentMtab 



parentMtab (somMethodTabs) 

A list of parent method tables, the first of which is the method table for the parent class for which the method is to be resolved. The 
SOM API specifies that the list of parent method tables for a given class be stored in the auxiliary class data structure of the class, in 
the parentMtab component. Thus, for the class "XYZ”, the parent method table list is found in location XYZCCIassData.parentMtab. 
Parent method table lists are available from class objects via the method call somGetPCIsMtabs. 



somParentResolve Parameter - mToken 



mToken (somToken) 

The method token for the method to be resolved. The SOM API requires that if the class "XYZ" introduces the static method "foo", 
then the method token for "foo" is found in the class data structure for "XYZ" (called XYZCIassData) in the structure member named 
"foo" (i.e., at XYZCIassData.foo). Method tokens can also be obtained using the somGetMethodToken method. 



somParentResolve Parameter - rc 



rc (somMethodPtr) 

A pointer to the somMethodProc (procedure) that implements the specified method, selected from the first method table. 



somParentResolve - Parameters 



parentMtab (somMethodTabs) 

A list of parent method tables, the first of which is the method table for the parent class for which the method is to be resolved. The 
SOM API specifies that the list of parent method tables for a given class be stored in the auxiliary class data structure of the class, in 
the parentMtab component. Thus, for the class "XYZ", the parent method table list is found in location XYZCCIassData.parentMtab. 
Parent method table lists are available from class objects via the method call somGetPCIsMtabs. 

mToken (somToken) 

The method token for the method to be resolved. The SOM API requires that if the class "XYZ" introduces the static method "foo", 
then the method token for "foo" is found in the class data structure for "XYZ" (called XYZCIassData) in the structure member named 
"foo" (i.e., at XYZCIassData.foo). Method tokens can also be obtained using the somGetMethodToken method. 

rc (somMethodPtr) 

A pointer to the somMethodProc (procedure) that implements the specified method, selected from the first method table. 



somParentResolve - Remarks 



This function is used by old, single-parent class binaries to make parent method calls. The function is obsolete, but is still supported. This 
function returns a pointer to the procedure that implements the specified method. This pointer is selected from the first method table in the 
parentMtab list. 



somParentResolve - Related Information 



Data Structures somMethodPtr(sombtype.h) somMethodTabs (somapi.h) somMToken(somapi.h) 

Functions 

• somResolveByName 

• som Resolve 

• somParentNumResolve 

• somClassResolve 

Methods 



• somDispatch 

• somClassDispatch 

• somFindMethod 

• somFindMethodOk 

• somGetMethodToken 




Macros 



SOMResolve 

SOMResolveNoCheck 



somParentResolve - Topics 
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somPrefixLevel 



somPrefixLevel - Syntax 



This function outputs blanks to prefix a line at the indicated level. 



long level; 
somPrefixLevel (level) ; 



somPrefixLevel Parameter - level 



level (long) 

The level at which the next line of output is to start. 



somPrefixLevel Parameter - rc 



rc 



somPrefixLevel - Parameters 



level (long) 

The level at which the next line of output is to start. 



rc 



somPrefixLevel - Remarks 



This function outputs blanks (via the somPrintf function) to prefix the next line of output at the indicated level. (The number of blanks 
produces is 2*level.) This function is useful when overriding the somDumpSelflnt method, which takes the level as an argument. 



somPrefixLevel - Related Information 



Functions 



somPrintf 

somVprintf 

somLPrintf 

SOMOutCharRoutine 



somPrefixLevel - Example Code 



#include <somcls.h> 
somPrefixLevel (5) ; 



somPrefixLevel - Topics 
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Glossary 



somPrintf 



somPrintf - Syntax 



This function prints a formatted string in the manner of the C printf function. 



string fmt; 

long rc; 

rc = somPrintf (fmt, • • • ) ; 



The values to be substituted 
into the format string. 



somPrintf Parameter - fmt 



fmt (string) 

The format string to be output. 



somPrintf Parameter - rc 



rc (long) 



Returns the number of characters written. 



somPrintf - Parameters 



fmt (string) 

The format string to be output. 



rc (long) 



Returns the number of characters written. 

somPrintf - Remarks 

This function prints a formatted string using function SOMOutCharRoutine, in the same manner as the C printf function. The 
implementation of SOMOutCharRoutine determines the destination of the output, while the C printf function is always directed to stdout. 
(The default output destination for SOMOutCharRoutine is stdout also, but this can be modified by the user.) 



somPrintf - 


Related Information 


Functions 





• somVprintf 

• somPrefixLevel 

• somLPrintf 

• SOMOutCharRoutine 

somPrintf - Example Code 

#include <somcls.h> 

somPrintf ( "The class name is %s.\n", _somGetClassName (ob j ) ) 



somPrintf - 


Topics 
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somRegisterld 



somRegisterld - Syntax 



This function registers a SOM ID and determines whether or not it was previously registered. 



somld id; 

int rc; 

rc = somRegisterld (id) ; 



somRegisterld Parameter - id 



id (somld) 



somRegisterld Parameter - rc 



rc (int) 



0 Returns 0 if the ID is already registered. 

1 Returns 1 if the ID is not already registered. 



somRegisterld - Parameters 



id (somld) 
rc (int) 

0 Returns 0 if the ID is already registered. 

1 Returns 1 if the ID is not already registered. 



somRegisterld - Remarks 



This function registers a SOM ID and converts it into an internal representation. If the ID is already registered, this function returns 0 and has 



no effect. Otherwise, this function returns 1 . 



somRegisterld - Related Information 



Data Structures 

• somld (sombtype.h). 



Functions 



• somCheckld 

• somldFromString 

• somStringFromld 

• somComparelds 

• somTotalReglds 

• somSetExpectedlds 

• somUniqueKey 

• somBeginPersistentlds 

• somEndPersistentlds 



somRegisterld - Example Code 



#include <som.h> 

static string s = "unregistered"; 
static somld sid = &s; 
main ( ) 

{ 

somEnvironmentNew ( ) ; 

SOM_Test (somRegisterld (sid) == 1); 

SOM_Test (somRegisterld (somldFromString ( "registered" ) ) == 0) ; 

} 



somRegisterld - Topics 
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somResolve 



somResolve - Syntax 



This function obtains a pointer to the procedure that implements a method for a particular SOM object. 



SOMObject obj; 

somMToken mToken; 

somMethodPtr rc; 

rc = somResolve (obj , mToken); 



somResolve Parameter - obj 



obj (SOMObject) 

A pointer to the object whose method procedure is required. 



somResolve Parameter - mToken 



mToken (somMToken) 

The method token for the method to be resolved. The SOM API requires that if the class "XYZ" introduces the static method "too", 
then the method token for "too" is found in the class data structure for "XYZ" (called XYZCIassData) in the structure member named 
"too" (i.e., at XYZCIassData.foo). Method tokens can also be obtained using the somGetMethodToken method. 



somResolve Parameter - rc 



rc (somMethodPtr) 

A pointer to the somMethodProc (procedure) that implements the specified method for the specified SOM object. 



somResolve - Parameters 



obj (SOMObject) 

A pointer to the object whose method procedure is required. 



mToken (somMToken) 

The method token for the method to be resolved. The SOM API requires that if the class "XYZ" introduces the static method "too", 
then the method token for "too" is found in the class data structure for "XYZ" (called XYZCIassData) in the structure member named 
"too" (i.e., at XYZCIassData.foo). Method tokens can also be obtained using the somGetMethodToken method. 



rc (somMethodPtr) 

A pointer to the somMethodProc (procedure) that implements the specified method for the specified SOM object. 



somResolve - Remarks 



This function returns a pointer to the procedure that implements the specified method for the specified SOM object. This pointer can then be 
used to invoke the method. The somResolve function can only be used to obtain a method procedure for a static method (one declared in 
an IDL or OIDL specification for a class); dynamic methods are not supported by method tokens. 

For C and C++ programmers, the SOM usage bindings for SOM classes provide more convenient mechanisms for invoking methods. These 
bindings use the SOM_Resolve and SOM_ResolveNoCheck macros, which construct a method token expression from the class name and 
method name, and call somResolve. 



somResolve - Related Information 



Data Structures 

• somMethodPtr (sombtype.h) 

• somMToken (somapl.h) 



Functions 



somResolveByName 

somParentResolve, 

somParentNumResolve 

somClassResolve 



Methods 

• somDispatch 

• somClassDispatch 

• somFindMethod 

• somFindMethodOk 

• somGetMethodToken 

Macros 



SOMResolve 

SOMResolveNoCheck 



somResolve - Example Code 



// SOM IDL for class A and class B 
#include <somobj.idl> 
module srExample { 

interface A : SOMObject { void foo(); implementation 
{ callstyle=oidl; }; }; 

interface B : A { implementation { foo: override; }; }; 

} ; 



// Example C++ program to implement and test module scrExample 




#def ine SOM_Module_srexample_Source 
#include <srExample . ih> 

#include <stdio.h> 

SOM_Scope void SOMLINK srExample_Af oo ( srExample_A *somSelf ) ; 
{ printf ("l\n") ; } 

SOM_Scope void SOMLINK srExample_Bf oo ( srExample_B *somSelf ) ; 

{ printf ("2\n") ; } 

main ( ) 

{ 

srExample_B objPtr = srExample_BNew ( ) ; 

/* This prints 2 */ 

( (somTD_srExample_A_foo) 

/* this method procedure expression cast is necessary */ 
somResolve (objPtr, srExample_AClassData . f oo) 

) /* end of method procedure expression */ 

(objPtr) ; 

} 



somResolve - Topics 
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somResolveByName 



somResolveByName - Syntax 



This function obtains a pointer to the procedure that implements a method for a particular SOM object. 



SOMObject 

string 

somMethodPtr 



ob j ; 

methodName; 

rc; 



rc = somResolveByName (obj , methodName); 



somResolveByName Parameter - obj 



obj (SOMObject) 

A pointer to the object whose method procedure is required. 



somResolveByName Parameter - methodName 



methodName (string) 

A character string representing the name of the method to be resolved. 



somResolveByName Parameter - rc 



rc (somMethodPtr) 



A pointer to the somMethodProc (procedure) that implements the specified method for the specified SOM object. 



somResolveByName - Parameters 

obj (SOMObject) 

A pointer to the object whose method procedure is required. 

methodName (string) 

A character string representing the name of the method to be resolved, 
rc (somMethodPtr) 

A pointer to the somMethodProc (procedure) that implements the specified method for the specified SOM object. 



somResolveByName - Remarks 



This function is used to obtain a pointer to the procedure that implements the specified method for the specified SOM object. The returned 
procedure pointer can then be used to invoke the method. The C and C++ usage bindings use this function to support name-lookup 
methods. 

This function can be used for invoking dynamic methods. However, the C and C++ usage bindings for SOM classes do not support dynamic 
methods, thus typedefs necessary for the use of dynamic methods are not available as with static methods. The function somApply provides 
an alternative mechanism for invoking dynamic methods that avoids the need for casting procedure pointers. 

Assuming the static method ''setSound,'' is introduced by the class "Animal", the following example will correctly invoke this method on an 
instance of "Animal" or one of its descendent classes. 




somResolveByName - Related Information 



Data Structures 

• somMethodPtr (sombtype.h) 

• SOMObject (somobj.idl) 

• string (somcorba.h) 



Functions 



som Resolve 
somParentResolve 
somParentNumResolve 
somClassResolve 



Methods 

• somDispatch 

• somClassDispatch 

• somFindMethod 

• somFindMethodOk 

Macros 



SOMResolve 

SOMResolveNoCheck 



somResolveByName - Example Code 



#include <animal.h> 
example (Animal myAnimal) 

{ 

somTD_Animal_set Sound 

setSoundProc = somResolveByName (myAnimal, "setSound") ; 
setSoundProc (myAnimal, "Roar!") ; 

} 



somResolveByName - Topics 



Select an item: 
Syntax 
Parameters 
Returns 
Remarks 
Example Code 
Related Information 
Glossary 



somSetException 



somSetException - Syntax 



This function sets an exception value in an Environment structure. 



Environment 
except ion_type 
string 
somToken 



*env; 

major; 

exceptionName ; 
params ; 



somSetException (env, major, exceptionName, 
params) ; 



somSetException Parameter - env 



env (Environment *) 

A pointer to the Environment structure in which to set the exception. This value must be either NULL or a value formerly obtained 
from the function somGetGlobalEnvironment. 



somSetException Parameter - major 



major (exception_type) 

major An integer representing the type of exception to set. 



somSetException Parameter - exceptionName 



exceptionName (string) 

The qualified name of the exception to set. The SOM Compiler defines, in the header files it generates for an interface, a constant 
whose value is the qualified name of each exception defined within the interface. This constant has the name 
"ex_<exceptionName>", where <exceptionName> is the qualified (scoped) exception name. Where unambiguous, the usage bindings 
also define the short form "ex_<exceptionName>", where <exceptionName> is unqualified. 



somSetException Parameter - params 



params (somToken) 

A pointer to an initialized exception structure value. No copy is made of this structure; hence, the caller cannot free it. The 
somExceptionFree function should be used to free the Environment structure that contains it. 



somSetException Parameter - rc 



somSetException - Parameters 



env (Environment *) 

A pointer to the Environment structure in which to set the exception. This value must be either NULL or a value formerly obtained 
from the function somGetGlobalEnvironment. 



major (exception_type) 

major An integer representing the type of exception to set. 



exceptionName (string) 

The qualified name of the exception to set. The SOM Compiler defines, in the header files it generates for an interface, a constant 
whose value is the qualified name of each exception defined within the interface. This constant has the name 
"ex_<exceptionName>", where <exceptionName> is the qualified (scoped) exception name. Where unambiguous, the usage bindings 
also define the short form "ex_<exceptionName>", where <exceptionName> is unqualified. 



params (somToken) 

A pointer to an initialized exception structure value. No copy is made of this structure; hence, the caller cannot free it. The 
somExceptionFree function should be used to free the Environment structure that contains it. 



rc 



somSetException - Remarks 

This function sets an exception value in an Environment structure. 



somSetException - Related Information 



Data Structures 

• Environment 

• exceptiontype 

• string (somcorba.h) 




Methods 



somExceptionld 
somException Value 
somExceptionFree 
somGetGlobalEnvironment 



somSetException - Example Code 



/* IDL declaration of class X: */ 

interface X : SOMObject { 

exception OUCH {long codel; long code2; }; 
void foo(in long arg) raises (OUCH); 

} ; 

/* implementation of foo method */ 

SOM_Scope void SOMLINK foo (X somSelf, Environment *ev, long arg) 

{ 

X_OUCH *exception_params; /* X_OUCH struct is defined 

in X's usage bindings */ 

if (arg > 5) /* then this is a very bad error */ 

{ 

exception_params = (X_OUCH*) SOM_Malloc (sizeof (X_OUCH) ) ; 
exception_params->codel = arg; 
except ion_params->code2 = arg-5; 
somSetException (ev, USER_EXCEPTION, ex_X_OUCH, 
except ion_params ) ; 

/* the Environment ev now contains an X_OUCH exception, with 

* the specified exception_params struct. The constant 

* ex_X_OUCH is defined in foo.h. Note that exception_params 

* must be malloced. 

*/ 

return ; 

} 



main ( ) 

{ 

Environment *ev; 

X x; 

somEnvironmentNew ( ) ; 
x = Xnew ( ) ; 

ev = somGetGlobalEnvironment ( ) ; 

X_foo (x, ev, 23); 

if (ev->_ma jor != NO_EXCEPTION) { 

printf("foo exception = %s\n", somExceptionld (ev) ) ; 
printf ( "codel = %d\n", 

( (X_OUCH*) somExceptionValue (ev) ) ->codel) ; 

/* finished handling exception. */ 

/* free the copied id and the original X_OUCH structure: */ 
somExceptionFree (ev) ; 

} 



somSetException - Topics 



Select an item: 




Syntax 

Parameters 

Returns 

Remarks 

Example Code 

Related Information 

Glossary 



somSetExpectedlds 



somSetExpectedlds - Syntax 



This function tells SOM how many unique SOM IDs a client program expects to use. 



unsigned long numlds; 
somSetExpectedlds (numlds) ; 



somSetExpectedlds Parameter - numlds 



numlds (unsigned long) 

The number of SOM IDs the client program expects to use. 



somSetExpectedlds Parameter - rc 



somSetExpectedlds - Parameters 



numlds (unsigned long) 

The number of SOM IDs the client program expects to use. 



rc 



somSetExpectedlds - Remarks 



This function informs the SOM run-time environment how many unique SOM IDs a client program expects to use during its execution. This 
has the potential of slightly improving the program's space and time efficiency, if the value specified is accurate. This function, if used, must 
be called prior to any explicit or implicit invocation of the somEnvironmentNew function to have any effect. 



somSetExpectedlds - Related Information 



Functions 



• somCheckld 

• somRegisterld 

• somldFromString 

• somStringFromld 

• somComparelds 

• somTotalReglds 

• somllniqueKey 

• somBeginPersistentlds 

• somEndPersistentlds 



somSetExpectedlds - Example Code 



#include <som.h> 
somSetExpectedlds (1000) ; 



somSetExpectedlds - Topics 



Select an item: 
Syntax 
Parameters 
Returns 
Remarks 
Example Code 
Related Information 
Glossary 



somSetOutChar 



somSetOutChar - Syntax 



This function changes the behavior of the somPrintf function. 

somTD_SOMOut Char Routine *outCharRtn; 

somSetOutChar (outCharRtn) ; 



somSetOutChar Parameter - outCharRtn 



outCharRtn (somTD_SOMOutCharRoutine *) 

A pointer to your routine that outputs a character in the way you want. 



somSetOutChar Parameter - rc 



somSetOutChar - Parameters 



outCharRtn (somTD_SOMOutCharRoutine *) 

A pointer to your routine that outputs a character in the way you want. 



rc 



somSetOutChar - Remarks 



This function is called to change the output character routine that somPrintf invokes. By default, somPrintf invokes a character output 
routine that goes to "stdout.” 

The execution of this function affects only the application (or thread) in which it occurs. Thus, this function is normally preferred over 
SOMOutCharRoutine for changing the output routine called by somPrintf, since SOMOutCharRoutine remains in effect for subsequent 
threads as well. 



Some samples of this function can be found in the "somapi.h" header file. 



somSetOutChar - Related Information 



Functions 



somPrintf 

SOMOutCharRoutine 



somSetOutChar - Topics 



Select an item: 

Syntax 

Parameters 

Returns 

Remarks 

Related Information 
Glossary 



somStringFromld 



somStringFromld - Syntax 



This function returns the string that a SOM ID represents. 

somld id; 

string rc; 

rc = somStringFromld ( id) ; 



somStringFromld Parameter - id 



id (somld) 

The SOM ID for which the corresponding string is needed. 



somStringFromld Parameter - rc 



rc (string) 

Returns the string that the given SOM ID represents. 



somStringFromld - Parameters 



id (somld) 

The SOM ID for which the corresponding string is needed, 
rc (string) 

Returns the string that the given SOM ID represents. 



somStringFromld - Remarks 



This function returns the string that a given SOM ID represents. 



somStringFromld - Related Information 



Data Structures 

• string (somcorba.h) 

• somid (sombtype.h) 



Functions 



• somCheckld 

• somRegisterld 

• somldFromString, 

• somComparelds, 

• somTotalReglds 

• somSetExpectedlds 

• somUniqueKey 

• somBeginPersistentlds 

• somEndPersistentlds 



somStringFromld - Example Code 




See function somBeginPersistentlds . 



somStringFromld - Topics 



Select an item: 
Syntax 
Parameters 
Returns 
Remarks 
Example Code 
Related Information 
Glossary 



somTotalReglds 



somTotalReglds - Syntax 



This function returns the total number of SOM IDs that have been registered. 

unsigned long rc; 
rc = somTotalReglds () ; 



somTotalReglds Parameter - rc 



rc (unsigned long) 

Returns the total number of SOM IDs that have been registered. 



somTotalReglds - Parameters 



rc (unsigned long) 



Returns the total number of SOM IDs that have been registered. 



somTotalReglds - Remarks 



This function returns the total number of SOM IDs that have been registered so far. This value can be used as a parameter to the 
somSetExpectedlds function to advise SOM about expected ID usage in later executions of a client program. 



somTotalReglds - Related Information 



Functions 

• somCheckld 

• somFtegisterld 

• somldFromString 

• somStringFromld 

• somComparelds 

• somSetExpectedlds 

• somUniqueKey 

• somBeginPersistentlds 

• somEndPersistentlds 



somTotalReglds - Example Code 



#include <som.h> 
main ( ) 

{ int i; 
somld id; 

somEnvironmentNew ( ) ; 

id = somldFromString ( "abc" ) 

i = somTotalReglds () ; 

id = somldFromString ( "abc" ) ; 

SOM_Test(i == somTotalReglds); 



somTotalReglds - Topics 



Select an item: 
Syntax 



Parameters 
Returns 
Remarks 
Example Code 
Related Information 
Glossary 



somUniqueKey 



somUniqueKey - Syntax 



This function returns the unique key associated with a SOM ID. 

somID id; 

unsigned long rc; 

rc = somUniqueKey (id) ; 



somUniqueKey Parameter - id 



id (somID) 

The SOM ID for which the unique key is needed. An unsigned long representing the unique key of the specified SOM ID. 



somUniqueKey Parameter - rc 



rc (unsigned long) 

An unsigned long representing the unique key of the specified SOM ID. 



somUniqueKey - Parameters 



id (somID) 

The SOM ID for which the unique key is needed. An unsigned long representing the unique key of the specified SOM ID. 
rc (unsigned long) 

An unsigned long representing the unique key of the specified SOM ID. 



somUniqueKey - Remarks 



This function returns the unique key associated with a SOM ID. The unique key for a SOM ID is a number that uniquely represents the string 
that the SOM ID represents. The unique key for a SOM ID is the same as the unique key for another SOM ID only if the two SOM IDs 
represent the same string. 



somUniqueKey - Related Information 



Data Structures 

• somld (sombtype.h) 



Functions 



• somCheckld 

• somFtegisterld 

• somldFromString 

• somStringFromld 

• somComparelds 

• somTotalReglds 

• somSetExpectedlds 

• somBeginPersistentlds 

• somEndPersistentlds 



somUniqueKey - Example Code 



#include <som.h> 
main ( ) 

{ 

unsigned long kl, k2; 

kl = somUniqueKey (somldFromString ( "abc" )) ; 

k2 = somUniqueKey (somldFromString ( "abc" )) ; 
SOM_Test (kl == k2); 

} 



somUniqueKey - Topics 



Select an item: 

Syntax 

Parameters 

Returns 

Remarks 

Example Code 



Related Information 
Glossary 



somVaBuf add 



somVaBuf_add - Syntax 



Adds an argument to the SOM buffer (somVaBuf) for variable arguments. 



somVaBuf vb; 

char *arg; 

int type; 

long rc; 

rc = somVaBuf_add (vb, arg, type); 



somVaBuf add Parameter - vb 



vb (somVaBuf) 

Value (somVaBuf) returned from somVaBuf_create function. 



somVaBuf_add Parameter - arg 



arg (char *) 

Pointer to the argument to be added to the vajist. 



somVaBuf_add Parameter - type 



type (int) 

Argument type (TCKind). 

The following are the supported TCKind types: 

• tkshort 

• tkushort 



• tklong 

• tkulong 

• tkfloat 

• tkdouble 

• tkchar 

• tkboolean 

• tkoctet 

• tkTypecode 

• tkenum 

• tkstring 

• tkpointer 



somVaBuf add Parameter - rc 



rc (long) 



If successful, a value of one is returned; otherwise, a value of zero is returned. 



somVaBuf add - Parameters 



vb (somVaBuf) 

Value (somVaBuf) returned from somVaBuf_create function, 
arg (char *) 

Pointer to the argument to be added to the vajist. 
type (int) 

Argument type (TCKind). 

The following are the supported TCKind types: 

• tkshort 

• tkushort 

• tklong 

• tkulong 

• tkfloat 

• tkdouble 

• tkchar 

• tkboolean 

• tkoctet 

• tkTypecode 

• tkenum 

• tkstring 

• tkpointer 



rc (long) 



If successful, a value of one is returned; otherwise, a value of zero is returned. 



somVaBuf add - Remarks 




This function adds the argument pointed to by arg to the vajist by using type for the size. 



somVaBuf_ 


_add - Related Information 


Functions 





• somVaBuf_create 

• somVaBuf_get_valist 

• somVaBuf_destroy 

• somvalistGetTarget 

• somvalistSetTarget 

somVaBuf_add - Example Code 

See function somVaBuf_create . 



somVaBuf_ 


_add - Topics 


Select an item: 
Syntax 
Parameters 
Returns 
Remarks 
Example Code 
Related Information 
Glossary 





somVaBuf 


create 



somVaBuf_ 


_create - Syntax 



Creates a SOM buffer (somVaBuf) for variable arguments from which the vajist will be built. 



char 

int 

somVaBuf 



*vb; 

size; 

rc; 



rc = somVaBuf_create (vb, size) ; 



somVaBuf create Parameter - vb 



vb (char *) 

Pointer to user-allocated memory or NULL. 



somVaBuf create Parameter - size 



size (int) 

Size of memory pointed at by vb , or else zero. 



somVaBuf create Parameter - rc 



rc (somVaBuf) 



If successful, somVaBuf is returned; otherwise, a NULL value is returned. 



somVaBuf create - Parameters 



vb (char *) 

Pointer to user-allocated memory or NULL, 
size (int) 

Size of memory pointed at by vb , or else zero, 
rc (somVaBuf) 



If successful, somVaBuf is returned; otherwise, a NULL value is returned. 



somVaBuf create - Remarks 



This function allocates, if necessary, and initializes a somVaBuf data structure. Memory is allocated if: 

• The size parameter is less than the size of the somVaBuf structure, 

• The size parameter is zero, or 

• The vb parameter is NULL. 

Note: Because the somVaBuf data structure is opaque, users cannot determine its size. Although this function accepts a user-allocated 
buffer, it is recommended that a NULL value be passed as the first argument. 



somVaBuf create - Related Information 



Functions 

• somVaBuf_add 

• somVaBuf_get_valist 

• somVaBuf_destroy 

• somvalistGetTarget 

• somvalistSetTarget 



somVaBuf_create - Example Code 



C EXAMPLE 

#include <somobj.h> 

void fl (SOMObject obj, Environment *ev) 

{ 

char *msg; 
va_list start_val; 
somVaBuf vb; 

char *msgl = "Good Morning"; 

vb = (somVaBuf ) somVaBuf_create (NULL, 0); 
somVaBuf_add (vb, (char *)&obj, tk_pointer) ; 

/* target for _set_msg */ 
somVaBuf_add (vb, (char *)&ev, tk_pointer) ; 

/* next argument */ 

somVaBuf_add (vb, (char *)&msgl, tk_pointer) ; 

/* final argument */ 

somVaBuf_get_valist (vb, &start_val) ; 

/* dispatch _set_msg on object */ 

SOMOb ject_somDispatch ( 

obj, /* target for somDispatch */ 

0, /* says ignore dispatched method result */ 

somldFromString ( "_set_msg" ) , /* the somld for _set_msg */ 
start_val) ; /* target and args for _set_msg */ 

/* dispatch _get_msg on obj: */ 

/* Get a fresh copy of the va_list */ 

somVaBuf_get_valist (vb, &start_val) ; 

SOMOb ject_somDi spat ch ( 

ob j , 

(somToken *)&msg. 




/* address to store dispatched result */ 
somldFromString ( n _get_msg" ) , 

start_val) ; /* target and arguments for _get_msg */ 
print f (" %s\n" , msg) ; 

somVaBuf_destroy (vb) ; 



C++ EXAMPLE 



#include <somobj.h> 

void fl (SOMObject obj, Environment *ev) 

{ 

char *msg; 
va_list start_val; 
somVaBuf vb; 

char *msgl = "Good Morning"; 



vb = (somVaBuf ) somVaBuf_create (NULL, 0); 
somVaBuf_add (vb, (char *)&obj, tk_pointer) ; 

/* target for _set_msg */ 
somVaBuf_add (vb, (char *) &ev, tk_pointer) ; 

/* next argument */ 

somVaBuf_add (vb, (char *)&msgl, tk_pointer) ; 

/* final argument */ 

somVaBuf_get_valist (vb, &start_val) ; 



/* dispatch _set_msg on obj: */ 

ob j->SOMOb ject_somDispatch ( 

0, /* says ignore the dispatched method result */ 

somldFromString ( "_set_msg" ) , /* the somld for _set_msg */ 
start_val) ; /* the target and arguments for _set_msg */ 

/* dispatch _get_msg on obj: */ 

/* Get a fresh copy of the va_list */ 

somVaBuf_get_valist (vb, &start_val) ; 

ob j->SOMOb ject_somDispatch ( 

(somToken *)&msg, 

/* address to hold dispatched method result */ 
somldFromString ( "_get_msg" ) , 

start_val) ; /* the target and arguments for _get_msg */ 

print f (" %s\n" , msg); 

somVaBuf_destroy ( vb) ; 



somVaBuf_create - Topics 
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Remarks 
Example Code 
Related Information 
Glossary 



somVaBuf_destroy 



somVaBuf_destroy - Syntax 



Releases the SOM buffer (somVaBuf) and its associated vajist. 



somVaBuf vb; 
somVaBuf _de st roy (vb) ; 



somVaBuf_destroy Parameter - vb 



vb (somVaBuf) 

Value (somVaBuf) returned from somVaBuf_create function. 



somVaBuf_destroy Parameter - rc 



rc 



somVaBuf_destroy - Parameters 



vb (somVaBuf) 

Value (somVaBuf) returned from somVaBuf_create function. 



rc 



somVaBuf_destroy - Remarks 



If somVaBuf was allocated by the somVaBuf_create function, the memory will be deallocated. 



somVaBuf_destroy - Related Information 



Functions 



somVaBuf_create 
somVaBuf_add 
somVaBuf_get_valist 
som valistGetT arget 
somvalistSetTarget 



somVaBuf_destroy - Example Code 



See function somVaBuf_create . 



somVaBuf_destroy - Topics 



Select an item: 
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Parameters 
Returns 
Remarks 
Example Code 
Related Information 
Glossary 



somVaBuf_get_valist 



somVaBuf_get_valist - Syntax 



Initializes a vajist from the SOM buffer (somVaBuf). 



somVaBuf vb; 

va_list *ap; 

somVaBuf_get_valist (vb, ap) ; 



somVaBuf_get_valist Parameter - vb 



vb (somVaBuf) 

Value (somVaBuf) returned from somVaBuf_create function. 



somVaBuf_get_valist Parameter - ap 



ap (vajist *) 

Pointer to a vajist. 



somVaBuf_get_valist Parameter - rc 



rc 



None. The user's vajist has been initialized from the vajist in somVaBuf. 



somVaBuf_get_valist - Parameters 



vb (somVaBuf) 

Value (somVaBuf) returned from somVaBuf_create function. 

ap (vajist *) 

Pointer to a vajist. 



rc 



None. The user's vajist has been initialized from the vajist in somVaBuf. 



somVaBuf_get_valist - Remarks 



This function copies the vajist in the somVaBuf structure to the passed vajist. 



somVaBuf_get_valist - Related Information 




Functions 



• somVaBuf_create 

• somVaBuf_add 

• somVaBuf_destroy 

• somvalistGetTarget 

• somvalistSetTarget 



somVaBuf_get_valist - Example Code 



See function somVaBuf_create . 



somVaBuf_get_valist - Topics 



Select an item: 
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Remarks 
Example Code 
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Glossary 



somvalistGetTarget 



somvalistGetTarget - Syntax 



Gets the first scalar value from a vajist without other side effects. 



va_list ap; 

unsigned long rc; 



rc = somvalistGetTarget (ap) ; 



somvalistGetTarget Parameter - ap 



ap (vajist) 

The vajist from which to get the value. 



somvalistGetTarget Parameter - rc 



rc (unsigned long) 



Scalar value from the vajist. 



somvalistGetTarget - Parameters 



ap (vajist) 

The vajist from which to get the value, 
rc (unsigned long) 



Scalar value from the vajist. 



somvalistGetTarget - Remarks 



Returns the first scalar value from the vajist without other side effects. 



somvalistGetTarget - Related Information 



Functions 



• somVaBuf_create 

• somVaBuf_add 

• somVaBuf_get_valist 

• somVaBuf_destroy 

• somvalistSetTarget 



somvalistGetTarget - Example Code 




va_list start_val; 
somVaBuf vb; 
unsigned long first; 

vb = (somVaBuf ) somVaBuf_create (NULL, 0) ; 
first = somvalistGet Target (start_val) ; 
somvalistSetTarget (start_val, first) ; 



somvalistGetTarget - Topics 
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Glossary 



somvalistSetTarget 



somvalistSetTarget - Syntax 



Modifies the vajist without other side effects. 



va_list ap; 

unsigned long val; 

unsigned long rc; 

rc = somvalistSetTarget (ap, val); 



somvalistSetTarget Parameter - ap 



ap (vajist) 

The vajist to modify. 



somvalistSetTarget Parameter - val 



val (unsigned long) 

Value to set in the first scalar slot. 



somvalistSetTarget Parameter - rc 



rc (unsigned long) 



None. 



somvalistSetTarget - Parameters 



ap (vajist) 

The vajist to modify. 

val (unsigned long) 

Value to set in the first scalar slot. 

rc (unsigned long) 



None. 



somvalistSetTarget - Remarks 



The somvalistSetTarget function replaces the first scalar value on the vajist with the value va/ that is passed in the call without any other 
side effects. 



somvalistSetTarget - Related Information 



Functions 



• somVaBuf_create 

• somVaBuf_add 

• somVaBuf_get_valist 

• somVaBuf_destroy 

• somvalistGetTarget 




somvalistSetTarget - Example Code 



va_list start_val; 
somVaBuf vb; 
unsigned long first; 

vb = (somVaBuf ) somVaBuf_create (NULL, 0) ; 
first = somvalistGetTarget (start_val) ; 

somvalistSetTarget (start_val, first) ; 



somvalistSetTarget - Topics 
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somVprintf 



somVprintf - Syntax 



This function prints a formatted string in the manner of the C vprintf function. 



string fmt; 

va_list ap; 

long rc; 

rc = somVprintf ( fmt , ap) ; 



somVprintf Parameter - fmt 



fmt (string) 

The format string to be output. 



somVprintf Parameter - ap 



ap (vajist) 

A vajist representing the values to be substituted into the format string. 



somVprintf Parameter - rc 



rc (long) 



Returns the number of characters written. 



somVprintf - Parameters 



fmt (string) 

The format string to be output, 
ap (vajist) 

A vajist representing the values to be substituted into the format string, 
rc (long) 



Returns the number of characters written. 



somVprintf - Remarks 



This function prints a formatted string using SOMOutCharRoutine, in the same manner as the C vprintf function. The implementation of 
SOMOutCharRoutine determines the destination of the output, while the C printf function is always directed to stdout. (The default output 
destination for SOMOutCharRoutine is stdout also, but this can be modified by the user.) 



somVprintf - Related Information 




Data Structures 



string (somcorba.h) 
vajist (stdarg.h) 



Functions 



somPrintf 

somPrefixLevel 

somLPrintf 

SOMOutCharRoutine 



somVprintf - Example Code 



#include <som.h> 
main ( ) 

{ 

va_list args; 
somVaBuf vb; 
float f = 3.1415; 
char c = ' a ' ; 
int one = 1 ; 

char *msg = "This is a test"; 

somEnvironmentNew ( ) ; /* Init environment */ 

vb = (somVaBuf ) somVaBuf_create (NULL, 0); 
somVaBuf_add (vb, (char *)&one, tk_long) ; 
somVaBuf_add (vb, (char *)&f, tk_float) ; 
somVaBuf_add (vb, (char *)&c, tk_char) ; 
somVaBuf_add (vb, (char *)&msg, tk_pointer) ; 
somVaBuf_get_valist (vb, &args) ; 

somVprintf (" %d, %f, %c, %s\n", args); 



somVprintf - Topics 



Select an item: 
Syntax 
Parameters 
Returns 
Remarks 
Example Code 
Related Information 
Glossary 



SOMCalloc 



SOMCalloc - Syntax 



This function allocates sufficient memory for an array of objects of a specified size. 



size_t num; 

size_t size; 

somToken rc; 

rc = (*SomCalloc) (num, size) ; 



SOMCalloc Parameter - num 



num (size_t) 

The number of objects for which space is to be allocated. 



SOMCalloc Parameter - size 



size (size_t) 

The size of the objects for which space to is to be allocated. 



SOMCalloc Parameter - rc 



rc (somToken) 



A pointer to the first byte of the allocated space. 



SOMCalloc - Parameters 



num (size_t) 

The number of objects for which space is to be allocated, 
size (size_t) 

The size of the objects for which space to is to be allocated. 



rc (somToken) 



A pointer to the first byte of the allocated space. 



SOMCalloc - Remarks 

This function allocates an amount of memory equal to num*size (sufficient memory for an array of num objects of size size). This function 
has the same interface as the C calloc function. It performs the same basic function as calloc with some supplemental error checking. If an 
error occurs, the SOMError function is called. This routine is replaceable by changing the value of the global variable SOMCalloc. 



SOMCalloc ■ 


■ Related Information 


Data Structures 





• somToken (sombtype.h) 

Functions 

• SOMMalloc 

• SOMRealloc 

• SOMFree 

SOMCalloc - Example Code 

See function somVprintf. 



SOMCalloc ■ 


■ Topics 


Select an item: 
Syntax 
Parameters 
Returns 
Remarks 
Example Code 
Related Information 
Glossary 





somClassInitFuncName 



somClassInitFuncName - Syntax 



This function returns the name of the function used to initialize classes in a DLL. 

string rc; 

rc = ( *somClassInitFuncName) (); 

somClassInitFuncName Parameter - rc 

rc (string) 

Returns the name of the function that should be used to initialize classes in a DLL. 



somClassInitFuncName ■ 


■ Parameters 


rc (string) 





Returns the name of the function that should be used to initialize classes in a DLL. 

somClassInitFuncName - Remarks 

This function is called by the SOM Class Manager to determine what function to call to initialize the classes in a DLL. The default version 
returns the string "SOMInitModule." The function can be replaced (so that the Class Manager will invoke a different function to initialize 
classes in a DLL) by changing the value of the global variable SOMCIassInitFuncName. 



somClassInitFuncName ■ 


■ Related Information 


Data Structures 





string (somcorba.h) 



Functions 



SOMLoadModule 

SOMDeleteModule 



somClassInitFuncName - Example Code 



#include <som.h> 

string XYZFuncName ( ) { return "XYZ"; } 

main ( ) 

{ 

SOMClassInitFuncName = XYZFuncName; 



somClassInitFuncName - Topics 



Select an item: 
Syntax 
Parameters 
Returns 
Remarks 
Example Code 
Related Information 
Glossary 



SOMDeleteModule 



SOMDeleteModule - Syntax 



This function unloads a dynamically linked library (DLL). 



somToken modHandle; 

int rc; 



rc = (*SOMDeleteModule) (modHandle) ; 



SOMDeleteModule Parameter - modHandle 



modHandle (somToken) 

The somToken for the DLL to be unloaded. This token is supplied by the SOMLoadModule function when it loads the DLL. 



SOMDeleteModule Parameter - rc 



rc (int) 



0 Returns 0 if successful. 

code Returns a non-zero system-specific error code if not successful. 



SOMDeleteModule - Parameters 



modHandle (somToken) 

The somToken for the DLL to be unloaded. This token is supplied by the SOMLoadModule function when it loads the DLL. 



rc (int) 



0 Returns 0 if successful. 

code Returns a non-zero system-specific error code if not successful. 



SOMDeleteModule - Remarks 



This function unloads the specified dynamically linked library (DLL). This routine is called by the SOM Class Manager to unload DLLs. This 
function can be replaced (thus changing the way the Class Manager unloads DLLS) by changing the value of the global variable 

SOMDeleteModule. 



SOMDeleteModule - Related Information 



Data Structures 

• somToken (sombtype.h) 



Functions 



SOMLoadModule 

SOMCIassInitFuncName 




SOMDeleteModule - Topics 



Select an item: 

Syntax 

Parameters 

Returns 

Remarks 

Related Information 
Glossary 



SOMError 



SOMError - Syntax 



This functions handles an error condition. 



int errorCode; 

string fileName; 

int lineNum; 

SOMError (errorCode, fileName, lineNum); 



SOMError Parameter - errorCode 



errorCode (int) 

An integer representing the error code of the error. 



SOMError Parameter - fileName 



fileName (string) 

The name of the file in which the error occurred. 



SOMError Parameter - lineNum 



lineNum (int) 

The line number where the error occurred. 



SOMError Parameter - rc 



rc 



SOMError - Parameters 



errorCode (int) 

An integer representing the error code of the error. 
fileName (string) 

The name of the file in which the error occurred. 
lineNum (int) 

The line number where the error occurred. 



rc 



SOMError - Remarks 



This function inspects the specified error code and takes appropriate action, depending on the severity of the error. The last digit of the error 
code indicates whether the error is classified as SOM_Fatal (9), SOM_Warn (2), or SOMJgnore (1 ). The default implementation of this 
function prints a message that includes the specified error code, filename, and line number, and terminates the current process if the error is 
classified as SOM_Fatal. The fileName and lineNum arguments specify where the error occurred. This routine can be replaced by changing 
the value of the global variable SOMError. 

For C and C++ programmers, SOM defines a convenience macro, SOM_Error, which invokes this function and supplies the last two 
arguments. 



SOMError - Related Information 



Macros 

• SOMTest 

• SOMTestC 




SOMWarnMsg 

SOMAssert 

SOMExpect 

SOMError 



SOMError - Topics 



Select an item: 

Syntax 

Parameters 

Returns 

Remarks 

Related Information 
Glossary 



somFree 



somFree - Syntax 



This function frees the specified block of memory. 



somToken ptr; 
somFree (ptr) ; 



somFree Parameter - ptr 



ptr (somToken) 

A pointer to the block of storage to be freed. 



somFree Parameter - rc 



rc 



somFree - Parameters 



ptr (somToken) 

A pointer to the block of storage to be freed. 



rc 



somFree - Remarks 



This function frees the block of memory pointed to by ptr. This function should only be called with a pointer previously allocated by 
SOMMalloc or SOMCalloc. This function has the same interface as the C free function. It performs the same basic function as free with 
some supplemental error checking. If an error occurs, the SOMError function is called. This routine is replaceable by changing the value of 
the global variable SOMFree. 

To free an object (rather than a block of memory), use the somFree method, rather than this function. 



somFree - Related Information 



Functions 



SOMCalloc 

SOMRealloc 

SOMMalloc 



Methods 

• somFree 



somFree - Example Code 



#include <som.h> 
main ( ) 

{ 

somToken ptr = SOMMalloc (20) ; 
SOMFree (ptr) ; 

} 



somFree - Topics 




Select an item: 
Syntax 
Parameters 
Returns 
Remarks 
Example Code 
Related Information 
Glossary 



SOMInitModule 



SOMInitModule - Syntax 



This function invokes the class creation routines for the classes contained in an OS/2 or Windows class library (DLL). 



long ma jorVersion; 
long minorVersion; 
string className; 

SOMInitModule (ma jorVersion, minorVersion, 
className) ; 



SOMInitModule Parameter - majorVersion 



majorVersion (long) 

The major version number of the class that was requested when the library was loaded. 



SOMInitModule Parameter - minorVersion 



minorVersion (long) 

The minor version number of the class that was requested when the library was loaded. 



SOMInitModule Parameter - className 



className (string) 

The name of the class that was requested when the library was loaded. 



SOMInitModule Parameter - rc 



SOMInitModule - Parameters 



majorVersion (long) 

The major version number of the class that was requested when the library was loaded. 

minorVersion (long) 

The minor version number of the class that was requested when the library was loaded. 
className (string) 

The name of the class that was requested when the library was loaded. 



rc 



SOMInitModule - Remarks 



On OS/2 or Windows, a class library (DLL) can contain the implementations for multiple classes, all of which should be created when the 
DLL is loaded. On OS/2, when loading a DLL, the SOM class manager determines the name of a DLL initialization function, and if the DLL 
exports a function of this name, the class manager invokes that function (whose purpose is to create the classes in the DLL). 
SOMInitModule is the default name for this DLL initialization function. 

On Windows, the SOM class manager does not call this function. It must be called from the default Windows DLL initialization function, 
LibMain. This call is made indirectly through the SOM_ClassLibrary macro (see the Example). 



SOMInitModule - Related Information 



Functions 

• SOMCIassInitFuncName 



Methods 



somGetlnitFunction 



Macros 



SOMCIassLibrary 




SOMInitModule - Example Code 



#include "xyz.h" 

#if def I BMC 

#pragma linkage (SOMInitModule, system) 

#endif 

SOMEXTERN void SOMLINK SOMInitModule (long ma jorVersion, 

long minorVersion, string className) 

{ 

SOM_IgnoreWarning (ma jorVersion) ; /* This function makes */ 
SOM_IgnoreWarning (minorVersion) ; /* no use of the passed */ 
SOM_IgnoreWarning (className); /* arguments. */ 

xyzNewClass, (A_Ma jorVersion, A_MinorVersion) ; 

} 



For Windows, also include the following function: 

#include <windows.h> 

int CALLBACK LibMain (HINSTANCE inst, 

WORD ds, 

WORD Heapsize, 

LPSTR cmdLine) 

{ 

SOM_IgnoreWarning (inst) ; 

SOM_ignoreWarning (ds) ; 

SOM_IgnoreWarning (heapSize) ; 
SOM_IgnoreWarning (cmdLine) ; 

SOM_ClassLibrary ("xyz.dll"); 

return 1; /* Indicate success to loader */ 

} 



SOMInitModule - Topics 



Select an item: 
Syntax 
Parameters 
Returns 
Remarks 
Example Code 
Related Information 
Glossary 



SOMLoadModule 



SOMLoadModule - Syntax 



This function loads the dynamically linked library (DLL) containing a SOM class. 



string 


className; 


string 


fileName; 


string 


functionName; 


int 


majorVersion ; 


long 


minorVersion ; 


somToken 


*modHandle; 


int 


rc; 


rc = (*SOMLoadModule) (class 



fi 



functionName, 
modHandle) ; 



ma jorVersion, 



leName, 

minorVersion, 



SOMLoadModule Parameter - className 



className (string) 

The name of the class whose DLL is to be loaded. 



SOMLoadModule Parameter - fileName 



fileName (string) 

The name of the DLL library file. This can be either a simple name or a fully-qualified pathname. 



SOMLoadModule Parameter - functionName 



functionName (string) 

The name of the routine to be called after the DLL is loaded. The routine is responsible for creating a class object for each class in 
the DLL. Typically, this argument will have the value SOMInitModule, obtained from the SOMCIassInitFuncName function. If no 
SOMInitModule entry exists in the DLL, the default version of this function looks for a routine named NewClass instead. If neither 
entry point is found, the default version of this function fails. 



SOMLoadModule Parameter - majorVersion 



majorVersion (int) 

The expected major version number of the class, to be passed to the initialization routine of the DLL. 



SOM Load Module Parameter - minorVersion 



minorVersion (long) 

The expected minor version number of the class, to be passed to the initialization routine of the DLL. 



SOMLoadModule Parameter - modHandle 



modHandle (somToken *) 

The address where this function should place a token that can be subsequently used by the SOMDeleteModule routine to unload the 
DLL. 



SOMLoadModule Parameter - rc 



rc (int) 



0 Returns 0 if successful. 

code Returns a non-zero system-specific error code if not successful. 



SOMLoadModule - Parameters 



className (string) 

The name of the class whose DLL is to be loaded. 
fileName (string) 

The name of the DLL library file. This can be either a simple name or a fully-qualified pathname. 

functionName (string) 

The name of the routine to be called after the DLL is loaded. The routine is responsible for creating a class object for each class in 
the DLL. Typically, this argument will have the value SOMInitModule, obtained from the SOMCIassInitFuncName function. If no 
SOMInitModule entry exists in the DLL, the default version of this function looks for a routine named NewClass instead. If neither 
entry point is found, the default version of this function fails. 

majorVersion (int) 

The expected major version number of the class, to be passed to the initialization routine of the DLL. 
minorVersion (long) 

The expected minor version number of the class, to be passed to the initialization routine of the DLL. 
modHandle (somToken *) 

The address where this function should place a token that can be subsequently used by the SOMDeleteModule routine to unload the 
DLL. 



rc (int) 



0 



Returns 0 if successful. 




code 



Returns a non-zero system-specific error code if not successful. 



SOM Load Module - Remarks 



This function loads the dynamically linked library (DLL) containing a SOM class. This routine is called by the SOM Class Manager to load 
DLLs. This function can be replaced (thus changing the way the Class Manager loads DLLS) by changing the value of the global variable 

SOMLoadModule. 



SOMLoadModule - Related Information 



Functions 



SOMDeleteModule 

SOMCIassInitFuncName 



SOMLoadModule - Topics 



Select an item: 

Syntax 

Parameters 

Returns 

Remarks 

Related Information 
Glossary 



SOMMalloc 



SOMMalloc - Syntax 



This function allocates the specified amount of memory. 



size_t size; 

somToken rc; 

rc = (*SOMMalloc) (size) ; 



SOMMalloc Parameter - size 



size (size_t) 

The amount of memory to be allocated, in bytes. 



SOMMalloc Parameter - rc 



rc (somToken) 

A pointer to the first byte of the allocated space. 



SOMMalloc - Parameters 



size (size_t) 

The amount of memory to be allocated, in bytes, 
rc (somToken) 

A pointer to the first byte of the allocated space. 



SOMMalloc - Remarks 



This function allocates size bytes of memory. This function has the same interface as the C malloc function. It performs the same basic 
function as malloc with some supplemental error checking. If an error occurs, the SOMError function is called. This routine is replaceable 
by changing the value of the global variable SOMMalloc. 



SOMMalloc - Related Information 



Functions 

SOMCalloc 

• SOMRealloc 

• SOMFree 



SOMMalloc - Example Code 




See function SOMFree. 



SOMMalloc - Topics 



Select an item: 
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Parameters 
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SOMOutCharRoutine 



SOMOutCharRoutine - Syntax 



This function prints a character. This function is replaceable. 



char c; 

int rc; 

rc = (^SOMOutCharRoutine) (c) ; 



SOMOutCharRoutine Parameter - c 



c (char) 

The character to be output. 



SOMOutCharRoutine Parameter - rc 



rc (int) 



0 Returns 0 if an error occurs. 

1 Returns 1 if no error occurs. 



SOMOutCharRoutine - Parameters 



c (char) 

The character to be output. 



rc (int) 



Returns 0 if an error occurs. 
Returns 1 if no error occurs. 



0 

1 



SOMOutCharRoutine - Remarks 



This function is a replaceable character output routine. It is invoked by SOM whenever a character is generated by one of the SOM 
error-handling or debugging macros. The default implementation outputs the specified character to stdout. To change the destination of 
character output, store the address of a user-written character output routine in global variable SOMOutCharRoutine. 

Another function, somSetOutChar, may be preferred over the SOMOutCharRoutine function. The somSetOutChar function enables each 
application (or thread) to have a customized character output routine. 



SOMOutCharRoutine - Related Information 



Functions 



• somVprintf 

• somPrefixLevel 

• somLPrintf 

• somPrinf 

• somSetOutChar 



SOMOutCharRoutine - Example Code 



#include <som.h> 

#pragma linkage (myCharacterOutputRoutine, system) 

/* Define a replacement routine: */ 

int SOMLINK myCharacterOutputRoutine (char c) 

{ 

(Customized code goes here) 




/* After the next stmt all output */ 

/* will be sent to the new routine */ 
SOMOutCharRoutine = myCharacterOutputRoutine; 



SOMOutCharRoutine - Topics 
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Parameters 
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Remarks 
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SOMRealloc 



SOMRealloc - Syntax 



This function changes the size of a previously allocated region of memory. 



somToken ptr; 

size_t size; 

somToken rc; 

rc = ( ^SOMRealloc) (ptr, size) ; 



SOMRealloc Parameter - ptr 



ptr (somToken) 

A pointer to the previously allocated region of memory. If NULL, a new region of memory of size bytes is allocated. 



SOMRealloc Parameter - size 



size (size_t) 

The size in bytes for the re-allocated storage. If zero, the memory pointed to by ptr is freed. 



SOMRealloc Parameter - rc 



rc (somToken) 

A pointer to the first byte of the re-allocated space. (A pointer is returned because the block of storage may need to be moved to 
increase its size.) 



SOMRealloc - Parameters 



ptr (somToken) 

A pointer to the previously allocated region of memory. If NULL, a new region of memory of size bytes is allocated, 
size (size_t) 

The size in bytes for the re-allocated storage. If zero, the memory pointed to by ptr is freed. 



rc (somToken) 

A pointer to the first byte of the re-allocated space. (A pointer is returned because the block of storage may need to be moved to 
increase its size.) 



SOMRealloc - Remarks 



The SOMRealloc function changes the size of the previously allocated region of memory pointed to by ptr so that it contains size bytes. 
The new size may be greater or less than the original size. The SOMRealloc function has the same interface as the C realloc function. It 
performs the same basic function as realloc with some supplemental error checking. If an error occurs, the SOMError function is called. 
This routine is replaceable by changing the value of the global variable SOMRealloc. 



SOMRealloc - Related Information 



Functions: 

• SOMCalloc 

• SOMMalloc 

• SOMFree 



SOMRealloc - Topics 



Select an item: 




Syntax 

Parameters 

Returns 

Remarks 

Related Information 
Glossary 



SOM Assert 



SOM Assert - Syntax 



This macro asserts that a boolean condition is true. 



boolean condition; 

long errorCode; 

SOM_Assert (condition, errorCode) ; 



SOM Assert Parameter - condition 



condition (boolean) 

A boolean expression that is expected to be TRUE (nonzero). 



SOM Assert Parameter - errorCode 



errorCode (long) 

The integer error code for the error to be raised if condition is FALSE. 



SOM Assert Parameter - rc 



rc 



SOM Assert - Parameters 



condition (boolean) 

A boolean expression that is expected to be TRUE (nonzero). 
errorCode (long) 

The integer error code for the error to be raised if condition is FALSE. 



rc 



SOM Assert - Remarks 



The SOM_Assert macro is used to place boolean assertions in a program: 

• If condition is FALSE, and errorCode indicates a warning-level error and SOM_WarnLevel is set to be greater than zero, then 
a warning message is output. 

• If condition is FALSE and errorCode indicates a fatal error, an error message is output and the process is terminated. 

• If condition is TRUE and SOM_AssertLevel is set to be greater than zero, then an informational message is output. 

External (Global) Data 

long SOM_WarnLevel ; /* default = 0 */ 

long SOM_AssertLevel ; /* default 0 */ 



SOMAssert - Expansion 



If condition is FALSE, and errorCode indicates a warning-level error and SOM_WarnLevel is set to be greater than zero, then a warning 
message is output. If condition is FALSE and errorCode indicates a fatal error, an error message is output and the process is terminated. If 
condition is TRUE and SOM_AssertLevel is set to be greater than zero, then an information message is output. 



SOM Assert - Related Information 



Macros: 

• SOMExpect 

• SOMTest 

• SOMTestC 



SOM Assert - Example Code 




#include <som.h> 
main ( ) 

{ 

SOM_WarnLevel = 1; 
SOM_Assert (2==2, 29); 



SOM Assert - Topics 



Select an item: 

Syntax 

Parameters 

Returns 

Remarks 

Expansion 

Example Code 

Related Information 

Glossary 



SOMCIassLibrary 



SOMCIassLibrary - Syntax 



This macro identifies the file name of the DLL for a SOM class library in a Windows LibMain function. 



string libname.dll; 
SOM_ClassLibrary (libname . dll) ; 



SOM CIassLibrary Parameter - libname.dll 



libname.dll (string) 

The name of the file containing the DLL (as the name would appear in a Windows LoadLibrary call). 



SOM CIassLibrary Parameter - rc 



rc 



None. 



SOMCIassLibrary - Parameters 



libname.dll (string) 

The name of the file containing the DLL (as the name would appear in a Windows LoadLibrary call). 

rc 

None. 



SOM CIassLibrary - Remarks 



Each Windows SOM class library must supply a Windows LibMain function. In LibMain, this macro identifies both the actual file name of the 
library as it would appear in a Windows LoadLibrary call and the location of the library's SOMInitModule function. This information is passed 
to the SOM Kernel, which in turn registers the library and schedules the execution of the SOMInitModule function. This macro can also be 
used in OS/2 class libraries within the context of a DLL "init/term" function. 

Typically, the SOM Kernel invokes the SOMInitModule function of each statically loaded class library during the execution of the 
somMainProgram function in the using application. For dynamically loaded class libraries, SOMInitModule is invoked immediately upon 
completion of the library's LibMain (or an OS/2 DLL "init/term") function. 

Because this macro expands to reference the SOMInitModule function, either a declaration of the SOMInitModule function, or the function 
itself, should precede the appearance of SOM_ClassLibrary in the current compilation unit, as shown in the Example below). 

The Example illustrates the use of the SOM_ClassLibrary macro in a Windows LibMain function. 



SOM_ClassLibrary - Related Information 



Macros 

• SOMMainProgram 

Functions 

• somMainProgram 



SOM CIassLibrary - Example Code 



#include <som.h> 

SOMEXTERN void SOMLINK SOMInitModule (long ma jorVersion, 

long minorVersion, 
string className) ; 




#include <windows.h> 

int CALLBACK LibMain (HINSTANCE inst, 

WORD ds, 

WORD Heapsize, 

LPSTR cmdLine) 

{ 

SOM_IgnoreWarning (inst) ; 

SOM_ignoreWarning (ds) ; 

SOM_IgnoreWarning (heapSize) ; 
SOM_IgnoreWarning (cmdLine) ; 

SOM_ClassLibrary ( "xyz . dll " ) ; 

return 1; /* Indicate success to loader */ 

} 



SOM CIassLibrary - Topics 
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SOM CreateLocalEnvironment Macro 



SOM_CreateLocalEnvironment Macro - Syntax 



This macro creates and initializes a local Environment structure. 



Environment *rc; 

rc = SOM_CreateLocalEnvironment Macro (); 



SOM CreateLocalEnvironment Macro Parameter - rc 



rc (Environment *) 



SOM_CreateLocalEnvironment Macro - Parameters 

rc (Environment *) 



SOM CreateLocal Environment Macro - Remarks 



The SOM_CreateLocalEnvironment macro creates a local Environment structure. This Environment structure can be passed to methods 
as the Environment argument so that exception information can be returned without affecting the global environment. 



SOM_CreateLocalEnvironment Macro - Expansion 



The SOMCreateLocalEnvironment expands to an expression of type (Environment *). 



SOM CreateLocalEnvironment Macro - Related Information 



Data Structures: 

• Environment (somcorba.h) 



Macros: 

• SOMDestroyLocalEnvironment 

• SOMInitEnvironment 

• SOMUninitEnvironment 

Functions: 



somGetGlobalEnvironment 



SOM CreateLocalEnvironment Macro - Example Code 



Environment *ev; 

ev = SOM_CreateLocalEnvironment ( ) ; 
_myMethod (ob j , ev) ; 

SOM_DestroyLocalEnvironment (ev) ; 




SOM CreateLocalEnvironment Macro - Topics 



Select an item: 

Syntax 

Parameters 
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Glossary 



SOMDestroyLocalEnvironment 



SOM_DestroyLocalEnvironment - Syntax 



This macro destroys a local Environment structure. 



Environment *env; 

SOM_DestroyLocalEnvironment (env) ; 



SOM DestroyLocalEnvironment Parameter - env 



env (Environment *) 

A pointer to the Environment structure to be discarded. 



SOM DestroyLocalEnvironment Parameter - rc 



rc 



SOM DestroyLocalEnvironment - Parameters 



env (Environment *) 

A pointer to the Environment structure to be discarded. 



rc 



SOM DestroyLocalEnvironment - Remarks 



The SOM_DestroyLocalEnvironment macro destroys a local Environment structure, such as one created using the 

SOMCreateLocalEnvironment macro. 



SOM_DestroyLocalEnvironment - Related Information 



Macros: 



SOMCreateLocalEnvironment 

SOMUninitEnvironment 



Functions: 



somExceptionFree 



SOM DestroyLocal Environment - Example Code 



Environment *ev; 

ev = SOM_CreateLocalEnvironment ( ) ; 
_myMethod (ob j , ev) ; 

SOM_DestroyLocalEnvironment (ev) ; 



SOM DestroyLocal Environment - Topics 
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SOM Error 



SOM Error - Syntax 



This macro reports an error condition. 

long errorCode; 

SOM_Error (errorCode) ; 



SOM Error Parameter - errorCode 



errorCode (long) 

The integer error code for the error to be reported. 



SOM Error Parameter - void 



SOM Error - Parameters 



errorCode (long) 

The integer error code for the error to be reported. 



void 



SOM Error - Remarks 



The SOM_Error macro invokes the SOMError error handling procedure with the specified error code, supplying the filename and line 
number where the macro was invoked. The default implementation of SOMError outputs a message containing the error code, filename, 
and line number. Additionally, if the last digit of the error code indicates a serious error (that is, value SOM_Fatal), the process is terminated. 



SOM_Error - Related Information 

Functions: 

SOMError 



SOM Error - Topics 
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SOMExpect 



SOMExpect - Syntax 



This macro asserts that a boolean condition is expected to be true. 



boolean condition; 
SOM_Expect (condition) ; 



SOM_Expect Parameter - condition 



condition (boolean) 

A boolean expression that is expected to be TRUE (nonzero). 



SOMExpect Parameter - rc 



SOMExpect - Parameters 



condition (boolean) 

A boolean expression that is expected to be TRUE (nonzero). 



rc 



SOM Expect - Remarks 



The SOM_Expect macro is used to place boolean assertions that are expected to be true into a program: 

• If condition is FALSE and SOM_WarnLevel is set to be greater than zero, then a warning message is output. 

• If condition is TRUE and SOM_AssertLevel is set to be greater than zero, then an informational message is output. 



SOM Expect - Expansion 



If condition is FALSE and SOM_WarnLevel is set to be greater than zero, then a warning message is output. If condition is TRUE and 
SOM_AssertLevel is set to be greater than zero, then an information message is output. 



SOM_Expect - Related Information 



Macros: 

• SOMAssert 

• SOMTest 

• SOMTestC 



SOM Expect - Example Code 




SOM_Expect (2==2) ; 



SOM Expect - Topics 



Select an item: 

Syntax 

Parameters 

Returns 

Remarks 

Expansion 

Example Code 

Related Information 

Glossary 



SOM GetClass 



SOMGetClass - Syntax 



This macro returns the class object of which a SOM object is an instance. 

SOMObject objPtr; 

SOMClass rc; 

rc = SOM_GetClass (objPtr) ; 



SOM GetClass Parameter - objPtr 



objPtr (SOMObject) 

A pointer to the object whose class is needed. 



SOM GetClass Parameter - rc 



rc (SOMClass) 



SOM GetClass - Parameters 



objPtr (SOMObject) 

A pointer to the object whose class is needed, 
rc (SOMCIass) 



SOM GetClass - Remarks 



The SOM_GetClass macro returns the class object of which obj is an instance. This is done without recourse to a method call on the 
object. The somGetClass method introduced by SOMObject is also intended to return the class of which an object is an instance, and the 
default implementation provided for this method by SOMObject uses the macro. 

Important Note: It is generally recommended that the somGetClass method call be used, since it cannot be known whether the class of an 
object wishes to provide special handling when its address is requested from an instance. But, there are (rare) situations where a method 
call cannot be made, and this macro can then be used. If you are unsure as to whether to use the method or the macro, you should use the 
method. 



SOM GetClass - Related Information 



Methods: 



somGetClass 



SOM GetClass - Example Code 



#include <somcls.xh> 

#include <animal.xh> 
main ( ) 

{ 

Animal *a = new Animal; 

SOMCIass cl s 1 = SOM_GetClass (a) ; 

SOMCIass cls2 = a->somGetClass ( ) ; 
if (clsl == cls2) 

printf ( "macro and method for getClass the same for Animal\n"); 
else 

printf ( "macro and method for getClass not same for Animal\n"); 




SOM GetClass - Topics 



Select an item: 
Syntax 
Parameters 
Returns 
Remarks 
Example Code 
Related Information 
Glossary 



SOM InitEnvironment 



SOMJnitEnvironment - Syntax 



This macro initializes a local Environment structure. 



Environment *env; 

SOM_InitEnvironment (env) ; 



SOM InitEnvironment Parameter - env 



env (Environment *) 

A pointer to the Environment structure to be initialized. 



SOM InitEnvironment Parameter - rc 



rc 



SOM InitEnvironment - Parameters 



env (Environment *) 

A pointer to the Environment structure to be initialized. 



rc 



SOM InitEnvironment - Remarks 



The SOMJnitEnvironment macro initializes a locally declared Environment structure. This Environment structure can then be passed to 
methods as the Environment argument so that exception information can be returned without affecting the global environment. 



SOMJnitEnvironment - Expansion 



The SOMJnitEnvironment initializes an Environment structure to zero. 



SOM InitEnvironment - Related Information 



Macros: 



SOMDestroyLocalEnvironment 

SOMCreateLocalEnvironment 

SOMUninitEnvironment 



Functions: 



somGetGlobalEnvironment 



SOMJnitEnvironment - Example Code 



Environment ev; 
SOM_InitEnvironment (&ev) ; 
_myMethod (ob j , &ev) ; 

SOM_UninitEnvironment (&ev) ; 



SOMJnitEnvironment - Topics 



Select an item: 

Syntax 

Parameters 



Returns 
Remarks 
Expansion 
Example Code 
Related Information 
Glossary 



SO M_Main Program 



SO M_Main Program - Syntax 



This macro identifies an application as a SOM program and registers an end-of-program exit procedure to release SOM resources when the 
application terminates. 



SOM_MainProgram ( ) ; 



SO M_Main Program - Parameters 

None 



SO MM ain Prog ram - Remarks 



This macro should appear near the beginning of each Windows application program that uses SOM or a SOM class library. It can also be 
used in OS/2 or AIX programs but is not generally required on these platforms. Any statically referenced SOM class libraries are initialized 
during the execution of this macro, and an end-of-program exit procedure is established to release SOM resources during normal program 
termination. (This macro combines the execution of the C/C++ "atexit" function with the SOM somMainProgram function and returns a 
reference to the global SOMCIassMgr object.) 



SOM_MainProgram - Related Information 



Functions 



somMainProgram 



Macros 



SOMCIassLibrary 



SO MM ain Prog ram - Example Code 



#include <som.h> 

#include <windows.h> 

int PASCAL WinMain (HINSTANCE inst, 
WORD ds, 

WORD Heapsize, 
LPSTR cmdLine) 

{ 

SOM_MainProgram ( ) ; 

/* Rest of main program follows */ 

} 



SOM MainProgram - Topics 



Select an item: 

Syntax 

Parameters 

Remarks 

Example Code 

Related Information 

Glossary 



SOM NoTrace 



SOM_NoTrace - Syntax 



This macro is used to turn off method debugging. 



<token> className; 

<token> methodName; 

SOM_NoTrace (className, methodName) ; 



SOM NoTrace Parameter - className 



className (<token>) 

The name of the class for which tracing will be turned off, given as a simple token rather than as a quoted string. 



SOM NoTrace Parameter - methodName 



methodName (<token>) 

The name of the method for which tracing will be turned off, given as a simple token rather than as a quoted string. 



SOM NoTrace - Parameters 



className (<token>) 

The name of the class for which tracing will be turned off, given as a simple token rather than as a quoted string. 

methodName (<token>) 

The name of the method for which tracing will be turned off, given as a simple token rather than as a quoted string. 



SOM NoTrace - Remarks 



The SOM_NoTrace macro is used to turn off method debugging. Within an implementation file for a class, before #including the 
implementation (.ih or ,xih) header file for the class, #define the <className>MethodDebug macro to be SOM_NoTrace. Then, 
<className>MethodDebug will have no effect. 



SOM_NoTrace - Expansion 

The SOM_NoTrace macro has a null (empty) expansion. 



SOM_NoTrace - Example Code 



#define AnimalMethodDebug (c, m) SOM_NoTrace (c, m) 
#include <animal.ih> 

/* Now AnimalMethodDebug does nothing */ 



SOM_NoTrace - Topics 




Select an item: 

Syntax 

Parameters 

Remarks 

Expansion 

Example Code 

Glossary 



SOM ParentNumResolve 



SOMParentNumResolve - Syntax 



This macro obtains a pointer to a method procedure from a list of method tables. It is used by C and C++ implementation bindings to 
implement parent method calls. 



(<token> introClass; 

long parentNum; 

somMethodTab parentMtabs; 

<token> ) methodName; 

SOM_ParentNumResolve (introClass, parentNum, 
parentMtabs, methodName) ; 



SOM ParentNumResolve Parameter - introClass 



introClass ((<token>) 

The name of the class that introduces methoc/Name . This name should be given as a simple token, rather than a quoted string (for 
example, An/ma/. rather than "Animal"). 



SOM ParentNumResolve Parameter - parentNum 



parentNum (long) 

The position of the desired parent. The first (leftmost) parent of a class has position 1 . 



SOM ParentNumResolve Parameter - parentMtabs 



parentMtabs (somMethodTab) 

A list of parent method tables acquired by invoking the somGetPCIsMtabs method on a class object. 



SOM ParentNumResolve Parameter - methodName 



methodName (<token> )) 

The name of the method to be resolved. This name should be given as a simple token, rather than a quoted string (for example, 
setSound rather than " setSound”). 



SOM ParentNumResolve - Parameters 



introClass ((<token>) 

The name of the class that introduces methodName . This name should be given as a simple token, rather than a quoted string (for 
example, Animat. rather than "Animat"). 

parentNum (long) 

The position of the desired parent. The first (leftmost) parent of a class has position 1 . 
parentMtabs (somMethodTab) 

A list of parent method tables acquired by invoking the somGetPCIsMtabs method on a class object. 



methodName (<token> )) 

The name of the method to be resolved. This name should be given as a simple token, rather than a quoted string (for example, 
setSound rather than "setSound"). 



SOM ParentNumResolve - Remarks 



This macro invokes the somParentNumResolve function to obtain a pointer to the static method procedure that implements the specified 
method for the specified parent. The method is specified by indicating the introducing class, introC/ass , and the method name, 
method/Vame . 



SOMParentNumResolve - Expansion 



The expansion of the macro produces an expression that is appropriately typed for application of the evaluated result to the indicated 
method's arguments, as illustrated in the Example. 



SOM ParentNumResolve - Related Information 



Functions 




somParentNumResolve 



Methods 



somGetPCIsMtabs 



SOM ParentNumResolve - Example Code 



#include <somcls.h> 

main ( ) 

{ 

SOMClassMgr * cm = somEnvironmentNew ( ) ; 
somMethodTabs mList = _somGetPClsMtabs (_SOMClass) ; 
SOM_ParentNumResolve (SOMOb ject , 1, mList, somDumpSelf Int ) 
(_SOMClass, 1) ; 

} 



SOM ParentNum Resolve - Topics 



Select an item: 
Syntax 
Parameters 
Remarks 
Expansion 
Example Code 
Related Information 
Glossary 



SOM Resolve 



SOMResolve - Syntax 



This macro obtains a pointer to a method procedure. 

Note: For backward compatibility, this method does not take an Environment parameter. 



SOMObject objPtr; 

<token> className; 

<token> methodName; 

RC somMethod; 



somMethod = SOM_Resolve (objPtr, className, 
methodName) ; 



SOMResolve Parameter - objPtr 



objPtr (SOMObject) 

A pointer to the object to which the resolved method procedure will be applied. 



SOM Resolve Parameter - className 



className (<token>) 

The name of the class that introduces methoc/Name . This name should be given as a simple token, rather than a quoted string (for 
example, Animai rather than "Animat"). 



SOM Resolve Parameter - methodName 



methodName (<token>) 

The name of the method to be resolved. This name should be given as a simple token, rather than a quoted string (for example, 
setSound rather than " setSound”). 



SOM_Resolve Parameter - somMethod 

somMethod (RC) 



SOM Resolve - Parameters 



objPtr (SOMObject) 

A pointer to the object to which the resolved method procedure will be applied. 
className (<token>) 

The name of the class that introduces methodName . This name should be given as a simple token, rather than a quoted string (for 
example, Animat rather than "Animal"). 

methodName (<token>) 

The name of the method to be resolved. This name should be given as a simple token, rather than a quoted string (for example, 




setSounc/ rather than " setSound'). 



somMethod (RC) 



SOM Resolve - Remarks 



The SOM_Resolve macro invokes the somResolve function to obtain a pointer to the static method procedure that implements the 
specified method for the specified object. This pointer can be used for efficient repeated casted method invocations on instances of the class 
of the object on which the resolution is done, or instances of subclasses of this class. The name of the class that introduces the method and 
the name of the method must be known to use this macro. Otherwise, use the somResolveByName, somFindMethod or 
somFindMethodOk method. 

The SOM_Resolve macro can only be used to obtain a method procedure for a static method (one defined in the IDL specification for a 
class); not a dynamic method. Unlike the SOM_ResolveNoCheck macro, the SOM_Resolve macro performs several consistency checks 
on the object pointed to by obj'Ptr. 



SOM Resolve - Expansion 



The SOM_Resolve macro uses the c/assName and methodName to construct the method token for the specified method, then invokes the 
somResolve function. Thus, the macro expands to an expression that represents the entry-point address of the method procedure. This 
value can be stored in a variable and used for subsequent invocations of the method. 



SOM Resolve - Related Information 



Macros: 

• SOMResolveNoCheck 

Functions: 

• somResolve 

• somClassResolve 

• somResolveByName 

Methods: 

• somFindMethod 

• somFindMethodOk 

• somDispatch 

• somClassDispatch 



SOM Resolve - Example Code 



Animal myObj = AnimalNewO; 
somMethodProc *procPtr; 

procPtr = SOM_Resolve (myObj , Animal, setSound); 




/* note that procPtr will need to be typecast when it is used */ 



SOM Resolve - Topics 



Select an item: 
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SOM ResolveNoCheck 



SOMResolveNoCheck - Syntax 



This macro obtains a pointer to a method procedure, without doing consistency checks. 



SOMObject objPtr; 

<token> className; 

<token> methodName; 

somMethodPtr rc; 

rc = SOM_ResolveNoCheck (objPtr , className, 
methodName) ; 



SOM ResolveNoCheck Parameter - objPtr 



objPtr (SOMObject) 

A pointer to the object to which the resolved method procedure will be applied. 



SOM ResolveNoCheck Parameter - className 



className (<token>) 



The name of the class that introduces methodName . This name should be given as a simple token, rather than a quoted string (for 
example, Animai rather than "Animal"). 



SOM ResolveNoCheck Parameter - methodName 



methodName (<token>) 

The name of the method to be resolved. This name should be given as a simple token, rather than a quoted string (for example, 
setSound rather than " setSound"). 



SOM ResolveNoCheck Parameter - rc 



rc (somMethodPtr) 



SOM ResolveNoCheck - Parameters 



objPtr (SOMObject) 

A pointer to the object to which the resolved method procedure will be applied. 
className (<token>) 

The name of the class that introduces methodName . This name should be given as a simple token, rather than a quoted string (for 
example, Animai rather than "Animal"). 

methodName (<token>) 

The name of the method to be resolved. This name should be given as a simple token, rather than a quoted string (for example, 
setSound rather than "setSound”). 

rc (somMethodPtr) 



SOM ResolveNoCheck - Remarks 



The SOM_ResolveNoCheck macro invokes the somResolve function to obtain a pointer to the method procedure that implements the 
specified method for the specified object. This pointer can be used for efficient repeated invocations of the same method on the same type 
of objects. The name of the class that introduces the method and the name of the method must be known at compile time. Otherwise, use 

the somFindMethod or somFindMethodOk method. 

The SOM_ResolveNoCheck macro can only be used to obtain a method procedure for a static method (one defined in the IDL specification 
for a class) and not a method added to a class at run time. Unlike the SOM_Resolve macro, the SOM_ResolveNoCheck macro does not 
perform any consistency checks on the object pointed to by obj'Ptr. 



SOM ResolveNoCheck - Expansion 




The SOM_ResolveNoCheck macro uses the c/assName and methoc/Name to construct an expression whose value is the method token 
for the specified method, then invokes the somResolve function. Thus, the macro expands to an expression that represents the entry-point 
address of the method procedure. This value can be stored in a variable and used for subsequent invocations of the method. 



SOM ResolveNoCheck - Related Information 



Macros: 

• SOMResolve 

Functions: 

• somResolve 

■ somClassResolve 

• somResolveByName 

Methods: 



somDispatch 

somClassDispatch 

somFindMethod 

somFindMethodOk 



SOMResolveNoCheck - Example Code 



Animal myObj = AnimalNew(); 
somMethodProc *procPtr; 

procPtr = SOM_ResolveNoCheck (myObj , Animal, setSound) 



SOM ResolveNoCheck - Topics 
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SOM SubstituteClass 



SOM_SubstituteClass - Syntax 



This macro provides a convenience macro for invoking the somSubstituteClass method. 



<token> oldClass; 

<token> newClass; 

SOM_SubstituteClass (oldClass, newClass) ; 



SOM SubstituteClass Parameter - oldClass 



oldClass (<token>) 

The name of the class to be substituted, given as a simple token rather than a quoted string. 



SOM SubstituteClass Parameter - newClass 



newClass (<token>) 

The name of the class that will replace o/dC/ass , given as a simple token rather than a quoted string. 



SOM SubstituteClass - Parameters 



oldClass (<token>) 

The name of the class to be substituted, given as a simple token rather than a quoted string. 
newClass (<token>) 

The name of the class that will replace o/dC/ass , given as a simple token rather than a quoted string. 



SOM SubstituteClass - Remarks 



The method somSubstituteClass requires existing class objects as arguments. Therefore, this macro first assures that the classes named 
o/dC/ass and newClass exist, and then calls the method somSubstituteClass with these class objects as arguments. 



SOM SubstituteClass - Related Information 



Methods 



somSubstituteClass 



SOM SubstituteClass - Example Code 



See the method somSubstituteClass . 



SOM SubstituteClass - Topics 
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SOM Test 



SOM_Test - Syntax 



This macro tests whether a boolean condition is true; if not, a fatal error is raised. 



boolean expression; 
SOM_Test (expression) ; 



SOM Test Parameter - expression 



expression (boolean) 

The boolean expression to test. 



SOMTest Parameter - rc 

rc 



SOM_Test - Parameters 

expression (boolean) 

The boolean expression to test. 

rc 



SOM Test - Remarks 



The SOM_Test macro tests the specified boolean expression: 

• If the expression is TRUE and SOM_AssertLevel is set to a value greater than zero, then an information message is output. 

• If the expression is FALSE, an error message is output and the process is terminated. 

Note: The SOM_TestC macro is similar, except that it only outputs a warning message in this situation. 

External (Global) Data 

long SOM_AssertLevel ; /* default is 0 */ 



SOM Test - Expansion 

The SOM_Test macro tests the specified boolean expression. If the expression is TRUE and SOM_AssertLevel is set to a value greater 
than zero, then an information message is output. If the expression is FALSE, an error message is output and the process is terminated. 



SOM Test - Related Information 



Macros: 

• SOMExpect 

• SOMAssert 

• SOMTestC 




SOMTest - Example Code 



#include <som.h> 
main ( ) 

{ 

SOM_Assert Level = 1; 

SOM_Test (1 = 1) ; 

} 



SOM Test - Topics 
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SOM TestC 



SOMTestC - Syntax 



This macro tests whether a boolean condition is true; if not, a warning message is output. 



boolean expression; 
SOM_TestC (expression) ; 



SOM TestC Parameter - expression 



expression (boolean) 

The boolean expression to test. 



SOM TestC Parameter - rc 



rc 



SOM_TestC - Parameters 

expression (boolean) 

The boolean expression to test. 

rc 



SOM TestC - Remarks 



The SOM_TestC macro tests the specified boolean expression: 

• If the expression is TRUE and SOM_AssertLevel is set to a value greater than zero, then an information message is output. 

• If the expression is FALSE and SOM_WarnLevel is set to a value greater than zero, then a warning message is output. 
Note: The SOM_Test macro is similar, except that it raises a fatal error in this situation. 



External (Global) Data 

long SOM_AssertLevel ; /* default is 0 */ 
long SOM_WarnLevel ; /* default is 0 */ 



SOM TestC - Expansion 



The SOM_TestC macro tests the specified boolean expression. If the expression is TRUE and SOM_AssertLevel is set to a value greater 
than zero, then an information message is output. If the expression is FALSE and SOM_WarnLevel is set to a value greater than zero, a 
warning message is output. 



SOM TestC - Related Information 



Macros: 



SOMExpect 

SOMAssert 

SOMTest 




SOM_TestC - Example Code 



#include <som.h> 
main ( ) 

{ 

SOM_WarnLevel = 1; 
SOM_TestC (1=1) ; 

} 



SOM TestC - Topics 
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SOM UninitEnvironment 



SOM_UninitEnvironment - Syntax 



This macro uninitializes a local Environment structure. 



Environment *env; 

SOM_UninitEnvironment (env) ; 



SOM UninitEnvironment Parameter - env 



env (Environment *) 



SOM UninitEnvironment Parameter - rc 



SOM UninitEnvironment - Parameters 



env (Environment *) 



SOM UninitEnvironment - Remarks 



The SOM_UninitEnvironment macro uninitializes a locally declared Environment structure. 



SOMJJninitEnvironment - Expansion 



The SOMUninitEnvironment invokes the somExceptionFree function on the specified Environment structure. 



SOM UninitEnvironment - Related Information 



Macros: 



SOMDestroyLocalEnvironment 

SOMInitEnvironment 



SOMJJninitEnvironment - Example Code 




Environment ev; 
SOM_InitEnvironment (&ev) ; 
_myMethod (ob j , &ev) ; 

SOM_UninitEnvironment (&ev) ; 



SOM_UninitEnvironment - Topics 
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SOM_WarnMsg 



SOM_WarnMsg - Syntax 



This macro reports a warning message. 



string msg; 
SOM_WarnMsg (msg) ; 



SOM_WarnMsg Parameter - msg 



msg (string) 

The warning message to be output. 



SOM_WarnMsg Parameter - rc 



rc 



SOM WarnMsg - Parameters 

msg (string) 

The warning message to be output. 

rc 

SOM WarnMsg - Remarks 

If SOM_WarnLevel is set to a value greater than zero, the SOM_WarnMsg macro prints the specified message, along with the filename 
and line number where the macro was invoked. 

SOM WarnMsg - Expansion 

If SOM_WarnLevel is set to a value greater than zero, the SOM_WarnMsg macro prints the specified message, along with the filename 
and line number where the macro was invoked. 



SOM_WarnMsg ■ 


- Related Information 


Methods: 

• SOMError 





SOM WarnMsg ■ 


- Topics 
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SOMCIass 



File stem: somcls 
Base 

SOMObject 

Metaclass 

SOMCIass 

(SOMCIass is the only class with itself as metaclass.) 

Ancestor Classes 
SOMObject 

Description 

SOMCIass is the root class for all SOM metaclasses. That is, all SOM metaclasses must be subclasses of SOMCIass or some other class 
derived from it. It defines the essential behavior common to all SOM classes. In particular, it provides a suite of methods for initializing class 
objects, generic methods for manufacturing instances of those classes, and methods that dynamically obtain or update information about a 
class and its methods at run time. 

Just as all SOM classes are expected to have SOMObject (or a class derived from SOMObject) as their base class, all SOM classes are 
expected to have SOMCIass or a class derived from SOMCIass as their metaclass. Metaclasses define "class" methods (sometimes called 
"factory" methods or "constructors") that manufacture objects from any class object that is defined as an instance of the metaclass. 

To define your own class methods, define your own metaclass by subclassing SOMCIass or one of its subclasses. Three methods that 
SOMCIass inherits and overrides from SOMObject are typically overridden by any metaclass that introduces instance data somlnit, 
somUninit, and somDumpSelflnt. The new methods introduced in SOMCIass that are frequently overridden are somNew, somRenew, 
and somClassReady. (See the descriptions of these methods for further information.) 

Other reasons for creating a new metaclass include tracking object instances, automatic garbage collection, interfacing to a persistent object 
store, or providing/managing information that is global to a set of object instances. 

Types 

typedef sequence <SOMClass> SOMClassSequence; 

struct somOf f setlnfo { 

SOMCIass els; 

long offset 

}; 

typedef sequence <somOf f set!nfo> SOMOffsets; 



New Methods 
Attributes 

readonly attribute somOffsets somlnstanceDataOf f sets 



_get_somlnstanceDataOffsets returns a sequence of structures, each of which indicates an ancestor of the receiver class (or the receiver 
class itself) and the offset to the beginning of the instance data introduced by the indicated class in an instance of the receiver class. The 
somOffsets information can be used in conjunction with information derived from calls to a SOM interface Repository to completely 
determine the layout of SOM objects at runtime. 

C++ Example 

ftinclude <somcls.xh> 
main ( ) 

{ 

int i; 

SOMClassMgr *scm = somEnvironmentNew ( ) ; 

somOffsets so = _SOMClass->_get_somInstanceDataOf f sets ( ) ; 
for < 1=0 ; i 

printf("In an instance of SOMCIass, %s data starts at %d\n", 
so ,_buf fer [i] ->cls->somGetName ( ) , 
so ,_buf fer [i] ->of fset) ; 




Introduced Methods 



The following list shows all the SOMCIass introduced methods. 

Group: Instance Creation (Factory) 

• somAllocate 

• somDeallocate 

• somNew 

• somNewNolnit 

• somRenew 

• somRenewNolnit 

• somRenewNolnitNoZero 

• somRenewNoZero 

Group: Initialization/Termination 

• somAddDynamicMethod 

• somClassReady 

Group: Access 

• somGetlnstancePartSize 

• somGetlnstanceSize 

• somGetlnstanceToken 

• somGetMemberToken 

• somGetMethodData, 

• somGetMethodDescriptor 

• somGetMethodlndex 

• somGetMethodToken 

• somGetName 

• somGetNthMethodData 

• somGetNthMethodlnfo 

• somGetNumMethods 

• somGetNumStaticMethods 

• somGetParents 

• somGetVersionNumbers 

Group: Testing 

• somCheckVersion 

• somDescendedFrom 

• somSupportsMethod 

Group: Dynamic 

• somFindMethod 

• somFindMethodOk 

• somFindSMethod 

• somFindSMethodld 

• somFindSMethodOk 

• somLookupmethod 

Overridden Methods 

The following list shows all the methods overridden by the SOMCIass class. These methods are overridden in order to modify the behavior 
defined by an ancestor class. 

• somDumpSelflnt 

• somDefaultlnit 

• somDestruct 

Deprecated Methods 

Use of the methods listed below is discouraged. There are three reasons for this: 

First, these methods are used in constructing classes, and this capability is provided by the function somBuildClass. Class construction in 
SOM is currently a fairly complex activity, and it is likely to become even more so as the SOMobjects kernel evolves. To avoid breaking 
source code that constructs classes, you are advised to always use somBuildClass to build SOM classes. Note that the SOM language 
bindings always use somBuildClass. 




Second, these methods are used for customizing aspects of SOM classes, such as method resolution and object creation. Doing this 
requires that metaclasses override various methods introduced by SOMCIass. However, if this is done without the Cooperation Framework 
that implements the SOM Metaclass Framework, SOMobjects cannot guarantee that applications will function correctly. Unfortunately, the 
Cooperation Framework (while available to SOM users as an experimental feature) is not officially supported by the SOMobjects Toolkit. So, 
this is another reason why the following methods are deprecated. 

Finally, some of these methods are now obsolete, so it seems appropriate that their use be discouraged. 



• somAddStaticMethod 

• somGetApplyStub 

• somGetClassData 

• somGetClassMtab 

• somGetlnstanceOffset 

• somGetMethodOffset 

• somGetParent 

• somGetPCIsMtab 

• somGetPCIsMtabs 

• somGetRdStub 

• somlnitClass 

■ somlnitMICIass 

• somOverrideMtab 

■ somOverrideSMethod 

• somSetClassData 

• somSetMethodDescriptor 

• _get_somDirectlnitClasses attribute 

• _set_somDirectlnitClasses attribute 



somAddDynamicMethod 



somAddDynamicMethod - Syntax 



This method adds a new dynamic instance method to a class. Dynamic methods are not part of the declared interface to a class of objects, 
and are therefore not supported by implementation and usage bindings. Instead, dynamic methods provide a way to dynamically add new 
methods to a class of objects during execution. SOM provides no standard protocol for informing a user of the existence of dynamic 
methods and the arguments they take. Dynamic methods must be invoked using name-lookup or dispatch resolution. 

Note: For backward compatibility, this method does not take an Environment parameter. 



SOMCIass 

somld 

somld 

somMethodPtr 

somMethodPtr 



receiver; 

methodld; 

met hodDe script or ; 

method; 

applyStub; 



somAddDynamicMethod (receiver , methodld, methodDescriptor , 
method, applyStub) ; 



somAddDynamicMethod Parameter - receiver 



receiver (SOMCIass) 



A pointer to a SOM class object. 



somAddDynamicMethod Parameter - methodld 



methodld (somld) 

A somld that names the method. 



somAddDynamicMethod Parameter - methodDescriptor 



methodDescriptor (somld) 

A somld appropriate for requesting information concerning the method from the SOM IR. This is currently of the form <className>: 
:<methodName>. 



somAddDynamicMethod Parameter - method 



method (somMethodPtr) 

A pointer to the procedure that will implement the new method. The first argument of this procedure is the address of the object on 
which it is being invoked. 



somAddDynamicMethod Parameter - applyStub 



applyStub (somMethodPtr) 

A pointer to a procedure that returns nothing and receives as arguments: a method receiver: an address where the return value from 
the method call is to be stored; a pointer to a method procedure; and a vajist containing the arguments to the method. The 
applyStub procedure (which is usually called by somDispatch must unload its vajist argument into separate variables of the correct 
type for the method, invoke its procedure argument on these variables, and then copy the result of the procedure invocation to the 
address specified by the return value argument. 



somAddDynamicMethod Parameter - rc 



rc 




somAddDynamicMethod - Parameters 



receiver (SOMCIass) 

A pointer to a SOM class object. 

methodld (somld) 

A somld that names the method. 

methodDescriptor (somld) 

A somld appropriate for requesting information concerning the method from the SOM IR. This is currently of the form <className>: 
:<methodName>. 

method (somMethodPtr) 

A pointer to the procedure that will implement the new method. The first argument of this procedure is the address of the object on 
which it is being invoked. 

applyStub (somMethodPtr) 

A pointer to a procedure that returns nothing and receives as arguments: a method receiver: an address where the return value from 
the method call is to be stored; a pointer to a method procedure; and a vajist containing the arguments to the method. The 
applyStub procedure (which is usually called by somDispatch must unload its vajist argument into separate variables of the correct 
type for the method, invoke its procedure argument on these variables, and then copy the result of the procedure invocation to the 
address specified by the return value argument. 



rc 



somAddDynamicMethod - Remarks 



The somAddDynamicMethod method adds a new dynamic instance method to the receiving class. This involves recording the method's 
ID, descriptor, method procedure (specified by method), and apply stub in the receiving class's method data. 

The arguments to this method should be non-null and obey the requirements expressed below. This is the responsibility of the implementor 
of a class, who in general has no knowledge of whether clients of this class will require use of the app/yStub argument. 



somAddDynamicMethod - Original Class 



SOMCIass 



somAddDynamicMethod - Related Methods 



Methods 



somGetMethodDescriptor 



somAddDynamicMethod - Example Code 




/* New dynamic method "newMethodl" for class "XXX" */ 
static char *somMN_newMethodl = "newMethodl"; 
static somld somId_newMethodl = &somMN_newMethodl ; 
static char *somDS_newMethodl = odq. XXX :: newMethodl " ; 
static somld somDI_newMethodl = &somDS_newMethodl ; 

static void SOMLINK somAP_newMethodl (SOMObject somSelf , 

void * retVal, 

somMethodProc * methodPtr, 

va_list ap) 

{ 

void* . .somSelf = va_arg ( ap, SOMObject); 

int argl = va_arg ( ap, int) ; 

SOM_IgnoreWarning ( retVal) ; 

( (somTD_SOMOb ject_newMethodl) methodPtr) ( somSelf, argl) ; 

} 

main ( ) 

{ 

_somAddDynamicMethod ( 

XXXClassData . classOb ject , /* Receiver (class object) */ 

somId_newMethodl , /* method name somld */ 

somDI_newMethodl , /* method descriptor somld */ 

(somMethodProc%rbl . *) newMethodl, /* method procedure */ 

(somMethodProc *) somAP&newMethodl ) ; /* method apply stub */ 

} 



somAddDynamicMethod - Topics 



Select an item: 
Syntax 
Parameters 
Returns 
Remarks 
Original Class 
Example Code 
Related Methods 
Glossary 



somAllocate 



somAllocate - Syntax 



This method supports class-specific memory allocation for class instances. It cannot be overridden. 
For backward compatibility, this method does not take an Environment parameter. 



SOMClass 



receiver; 



long 

string 



size; 

rc; 



rc = somAllocate (receiver, size); 



somAllocate Parameter - receiver 



receiver (SOMCIass) 

A pointer to the class object whose memory allocation method is desired. 



somAllocate Parameter - size 



size (long) 

The number of bytes to be allocated. 



somAllocate Parameter - rc 



rc (string) 



A pointer to the first byte of the allocated memory region. 
If sufficient memory is not available. 



string 

NULL 



somAllocate - Parameters 



receiver (SOMCIass) 

A pointer to the class object whose memory allocation method is desired, 
size (long) 

The number of bytes to be allocated, 
rc (string) 



string A pointer to the first byte of the allocated memory region. 

NULL If sufficient memory is not available. 



somAllocate - Remarks 



When building a class, the somBuildClass function is responsible for registering the procedure that will be executed when this method is 
invoked on the class. The default procedure registered by somBuildClass uses the SOMMalloc function, but the IDL modifier somallocate 
can be used in the SOM IDL class implementation section to indicate a different procedure. Users of this method should be sure to use the 
dual method, somDeallocate, to free allocated storage. Also, if the IDL modifier somallocate is used to indicate a special allocation routine, 
the IDL modifier somdeallocate should be used to indicate a dual procedure to be called when the somDeallocate method is invoked. 



somAllocate - Original Class 



SOMCIass 



somAllocate - Related Methods 



Methods 



somDeallocate 



somAllocate - Example Code 



#include <som.xh> 

#<somcls . xh> 
main ( ) 

{ 

SOMClassMgr *cm = somEnvironmentNew ( ) ; 

/* Use SOMCIass' s instance allocation method */ 
string newRegion = _SOMClass->somAllocate (20) ; 

} 



somAllocate - Topics 



Select an item: 
Syntax 
Parameters 
Returns 
Remarks 
Original Class 
Example Code 
Related Methods 
Glossary 



somCheckVersion 



somCheckVersion - Syntax 



This method checks a class for compatibility with the specified major and minor version numbers. Not generally overridden. 



Note: For backward compatibility, this method does not take an Environment parameter. 



SOMClass 

long 

long 

boolean 



receiver; 
ma jorVersion ; 
minorVersion ; 
rc; 



rc = somCheckVersion (receiver , ma jorVersion, 
minorVersion) ; 



somCheckVersion Parameter - receiver 



receiver (SOMClass) 

A pointer to the SOM class whose version information should be checked. 



somCheckVersion Parameter - majorVersion 



majorVersion (long) 

This value usually changes only when a significant enhancement or incompatible change is made to a class. 



somCheckVersion Parameter - minorVersion 



minorVersion (long) 

This value changes whenever minor enhancements or fixes are made to a class. Class implementors usually maintain downward 
compatibility across changes in the m/norl/ers/on number. 



somCheckVersion Parameter - rc 



rc (boolean) 



1 Returns 1 (true) if the implementation of this class is compatible with the specified major and minor 

version number. 

0 Returns 0 (false) if the implementation of this class is not compatible with the specified major and 

minor version number. 



somCheckVersion - Parameters 



receiver (SOMCIass) 

A pointer to the SOM class whose version information should be checked. 

majorVersion (long) 

This value usually changes only when a significant enhancement or incompatible change is made to a class. 

minorVersion (long) 

This value changes whenever minor enhancements or fixes are made to a class. Class implementors usually maintain downward 
compatibility across changes in the m/nor\/ers/on number. 

rc (boolean) 



1 Returns 1 (true) if the implementation of this class is compatible with the specified major and minor 

version number. 

0 Returns 0 (false) if the implementation of this class is not compatible with the specified major and 

minorversion number. 



somCheckVersion - Remarks 



This method checks the receiving class for compatibility with the specified major and minor version numbers. An implementation is 
compatible with the specified version numbers if it has the same major version number and a minor version number that is equal to or 
greater than m/norVers/on . The version number pair (0,0) is considered to match any version. 

This method is called automatically after creating a class object to verify that a dynamically loaded class definition is compatible with a client 
application. 



somCheckVersion - Original Class 

SOMCIass 



somCheckVersion - Example Code 



#include <animal.h> 
main ( ) 

{ 




An ima 1 myAn ima 1 ; 
myAnimal = AnimalNew(); 

if (_somCheckVersion (_Animal, 0, 0)) 

somPrintf ( "Animal IS compatible with 0.0\n" ); 
else 

somPrintf ( "Animal IS NOT compatible with 0.0\n"); 

if (_somCheckVersion (_Animal, 1, 1)) 

somPrintf ( "Animal IS compatible with l.l\n"); 
else 

somPrintf ( "Animal IS NOT compatible with l.l\n"; 

_somFree (myAnimal) ; 

} 



Assuming that the implementation of Animal is version 1 .0, this program produces the following output: 

Animal IS compatible with 0.0 
Animal IS NOT compatible with 1 . 1 



somCheckVersion - Topics 



Select an item: 
Syntax 
Parameters 
Returns 
Remarks 
Original Class 
Example Code 
Glossary 



somClassReady 



somClassReady - Syntax 



This method indicates that a class has been constructed and is ready for normal use. Designed to be overridden. 
For backward compatibility, this method does not take an Environment parameter. 

SOMClass receiver; 
somClassReady (receiver) ; 



somClassReady Parameter - receiver 



receiver (SOMCIass) 

A pointer to the class object that should be registered. 



somClassReady Parameter - rc 



somClassReady - Parameters 



receiver (SOMCIass) 

A pointer to the class object that should be registered. 



rc 



somClassReady - Remarks 



This method is invoked automatically by the somBuildClass function after constructing and initializing a class object. The default 
implementation of this method provided by SOMCIass simply registers the newly constructed class with SOMCIassMgrObject. Metaclasses 
can override this method to augment class construction with additional registration protocol. 

To have special processing done when a class object is created, you must define a metaclass for the class that overrides this method. The 
final statement in any overriding method should invoke the parent method to ensure that the class is properly registered with 
SOMCIassMgrObject. Users of the C and C++ implementation bindings for SOM classes should never invoke this method directly; it is 
invoked automatically during class construction. 



somClassReady - Original Class 

SOMCIass 



somClassReady - Topics 



Select an item: 
Syntax 
Parameters 
Returns 



Remarks 
Original Class 
Glossary 



somDeallocate 



somDeallocate - Syntax 



This method frees memory originally allocated by the somAllocate method from the same class object. It cannot be overridden. 
For backward compatibility, this method does not take an Environment parameter. 



SOMClass receiver; 

string memPtr; 

somDeallocate (receiver, memPtr) ; 



somDeallocate Parameter - receiver 



receiver (SOMClass) 

A pointer to the class object whose somAllocate was originally used to allocate the memory now to be freed. 



somDeallocate Parameter - memPtr 



memPtr (string) 

A pointer to the first byte of the region of memory that is to be freed. 



somDeallocate Parameter - rc 



rc 



somDeallocate - Parameters 



receiver (SOMCIass) 

A pointer to the class object whose somAllocate was originally used to allocate the memory now to be freed. 
memPtr (string) 

A pointer to the first byte of the region of memory that is to be freed. 



rc 



somDeallocate - Remarks 



The somDeallocate method is intended for use to free memory allocated using its dual method, somAllocate. When building a class, the 
somBuildClass function is responsible for registering the procedure that will be executed when this method is invoked on the class. The 
default procedure regisistered by somBuildClass uses the SOMFree function, but the IDL modifier somdeallocate can be used in the SOM 
IDL class implementation section to indicate a different procedure. Users of this method should be sure that the dual method, somAllocate, 
was originally used to allocate storage. Also, if the IDL modifier somdeallocate is used to indicate a special deallocation routine, the IDL 
modifier somallocate should be used to indicate a dual procedure to be called when somAllocate is invoked. 



somDeallocate - Original Class 

SOMCIass 



somDeallocate - Related Methods 

Methods 

• somAllocate 



somDeallocate - Topics 



Select an item: 
Syntax 
Parameters 
Returns 
Remarks 
Original Class 
Related Methods 
Glossary 



somDescendedFrom 



somDescendedFrom - Syntax 



This method tests whether one class is derived from another. Not generally overridden. 
For backward compatibility, this method does not take an Environment parameter. 



SOMClass receiver; 

SOMClass aClassObj; 

boolean rc; 

rc = somDescendedFrom (receiver , aClassObj) ; 



somDescendedFrom Parameter - receiver 



receiver (SOMClass) 

A pointer to the class object to be tested. 



somDescendedFrom Parameter - aClassObj 



aClassObj (SOMClass) 

A pointer to the potential ancestor class. 



somDescendedFrom Parameter - rc 



rc (boolean) 



Returns 1 (true) if rece/Ver is derived from aC/assObj. 
Returns 0 (false) if rece/Ver is not derived from aC/assObj. 



1 

0 



somDescendedFrom - Parameters 



receiver (SOMCIass) 

A pointer to the class object to be tested. 

aClassObj (SOMCIass) 

A pointer to the potential ancestor class. 

rc (boolean) 



1 Returns 1 (true) if rece/Ver is derived from aC/assObj. 

0 Returns 0 (false) if rece/Ver is not derived from aC/assObj. 



som Descended From - Remarks 



This method tests whether the receiver class is derived from a given class. For programs that use classes as types, this method can be 
used to ascertain whether the type of one object is a subtype of another. 

This method considers a class object to be descended from itself. 



somDescendedFrom - Original Class 



SOMCIass 



somDescendedFrom - Related Methods 



Methods 

• somlsA 

• somlsInstanceOf 



somDescendedFrom - Example Code 



#include <dog.h> 

/* 

Note: Dog is a subclass of Animal. 

*/ 

main ( ) 

{ 

AnimalNewClass (0,0); 

DogNewClass (0,0) ; 

if (_somDescendedFrom (_Dog, _Animal) ) 

somPrintf ( "Dog IS descended from Animal\n"); 




else 



somPrintf ( "Dog is NOT descended from Animal\n"); 
if (_somDescendedFrom (_Animal, _Dog) ) 

somPrintf ( "Animal IS descended from Dog\n"); 
else 

somPrintf ( "Animal is NOT descended from Dog\n"); 



This program produces the following output: 

Dog IS descended from Animal 
Animal is NOT descended from Dog 



somDescendedFrom - Topics 



Select an item: 
Syntax 
Parameters 
Returns 
Remarks 
Original Class 
Example Code 
Related Methods 
Glossary 



somFindMethod 



somFindMethod - Syntax 



This method finds the method procedure for a method and indicates whether it represents a static method or a dynamic method, 
generally overridden. 

For backward compatibility, this method does not take an Environment parameter. 



SOMClass 

somld 

somMethodPtr 

boolean 



receiver; 

methodld; 

m; 

rc; 



rc = somFindMethod (receiver, methodld, m) ; 



somFindMethod Parameter - receiver 



receiver (SOMCIass) 

A pointer to the class object whose method is desired. 



somFindMethod Parameter - methodld 



methodld (somld) 

An ID that represents the name of the desired method. The somldFromString function can used to obtain an ID from the method's 
name. 



somFindMethod Parameter - m 



m (somMethodPtr) 

A pointer to the location in memory where a pointer to the specified method's procedure should be stored. The method stores a NULL 
pointer in this location (if the method does not exist) or a value that can be called. 



somFindMethod Parameter - rc 



rc (boolean) 



TRUE 

FALSE 



Returns TRUE when the method procedure can be called directly and FALSE when the method 
procedure is a dispatch function. 

Returns FALSE when the method procedure is a dispatch function. 



somFindMethod - Parameters 



receiver (SOMCIass) 

A pointer to the class object whose method is desired, 
methodld (somld) 

An ID that represents the name of the desired method. The somldFromString function can used to obtain an ID from the method's 
name. 

m (somMethodPtr) 

A pointer to the location in memory where a pointer to the specified method's procedure should be stored. The method stores a NULL 
pointer in this location (if the method does not exist) or a value that can be called. 

rc (boolean) 



TRUE Returns TRUE when the method procedure can be called directly and FALSE when the method 

procedure is a dispatch function. 

Returns FALSE when the method procedure is a dispatch function. 



FALSE 




somFindMethod - Remarks 



This method performs name-lookup method resolution, determines the method procedure appropriate for performing the indicated method 
on instances of the receiving class, and loads m with the method procedure address. For static methods, method procedure resolution is 
done using the instance method table of the receiving class. 

Name-lookup resolution must be used to invoke dynamic methods. Also, name-lookup can be useful when different classes introduce 
methods of the same name, signature, and desired semantics, but it is not known until runtime which of these classes should be used as a 
type for the objects on which the method is to be invoked. If the signature of a method is a not known, then method procedures cannot be be 
used directly, and the somDispatch method can be used after dynamically discovering the signature to allow the correct arguments can be 
placed on a vajist. 

As with any method that returns procedure pointers, this method allows repeated invocations of the same method procedure to be 
programmed. If this is done, it up to the programmer to prevent runtime errors by assuring that each invocation is performed either on an 
instance of the class used to resolve the method procedure or of some class derived from it. Whenever using SOM method procedure 
pointers, it is necessary to indicate the arguments to be passed and the use of system linkage to the compiler, so it can generate a correct 
procedure call. The way this is done depends on the compiler and the system being used. Flowever, C and C++ usage bindings provide an 
appropriate typedef for static methods. The name of the typedef is based on the name of the class that introduces the method, as illustrated 
in the example below. 

If the class does not support the specified method, then * m is set to NULL and the return value is meaningless. Otherwise, the returned 
result is true if the indicated method was a static method. 



somFindMethod - Original Class 



SOMCIass 



somFindMethod - Related Methods 



Methods 

• somFindSMethod 

• somFindSMethodOK 

• somSupportsMethod 

• somDispatch, 

• somClassDispatch 

Functions 

• somApply 

• som Resolve 

• somClassResolve 

• somResolveByName 

• somParentNumResolve 

Macros 



SOMResolve 

SOMResolveNoCheck 

SOMParentNumResolve 



somFindMethod - Example Code 




Assuming that the An/ma/ class introduces the method setSound , the type name for the setSound method procedure type will be 
somTD_An/ma/_setSound , as illustrated in the Example. 

ftinclude <animal.h> 
void main ( ) 

{ 

An ima 1 my An ima 1 ; 
somld somId_setSound; 
somTD_Animal_set Sound methodPtr; 

Environment *ev = somGetGlobalEnvironment ( ) ; 

my Animal = AnimalNew(); 

/* 

Note: Next three lines are equivalent to 
_setSound (my Animal , ev, "Roar! ! !") ; 

*/ 

somId_setSound = somldFromString ( "setSound" ) ; 

_somFindMethod (_somGetClass (my Animal) , 

somId_setSound, &methodPtr) ; 
methodPtr (my Animal , ev, "Roar! ! !") ; 

/* */ 

_display (my Animal , ev) ; 

_somFree (my Animal) ; 



/* 

Program Output: 
This Animal says 
Roar ! ! ! 

*/ 



somFindMethod - Topics 



Select an item: 
Syntax 
Parameters 
Returns 
Remarks 
Original Class 
Example Code 
Related Methods 
Glossary 



somFindMethodOk 



somFindMethodOk - Syntax 



This method finds the method procedure for a method and indicates whether it represents a static method or a dynamic method. Not 
generally overridden. 

For backward compatibility, this method does not take an Environment parameter. 



SOMClass receiver; 

somld methodld; 

somMethodPtr m; 
boolean rc; 

rc = somFindMethodOk (receiver, methodld, m) ; 



somFindMethodOk Parameter - receiver 



receiver (SOMClass) 

A pointer to the class object whose method is desired. 



somFindMethodOk Parameter - methodld 



methodld (somld) 

An ID that represents the name of the desired method. The somldFromString function can used to obtain an ID from the method's 
name. 



somFindMethodOk Parameter - m 



m (somMethodPtr) 

A pointer to the location in memory where a pointer to the specified method's procedure should be stored. Both methods store a 
NULL pointer in this location (if the method does not exist) or a value that can be called. 



somFindMethodOk Parameter - rc 



rc (boolean) 



TRUE 

FALSE 



Returns TRUE when the method procedure can be called directly and FALSE when the method 
procedure is a dispatch function. 

Returns FALSE when the method procedure is a dispatch function. 



somFindMethodOk - Parameters 



receiver (SOMCIass) 

A pointer to the class object whose method is desired. 



methodld (somld) 

An ID that represents the name of the desired method. The somldFromString function can used to obtain an ID from the method's 
name. 



m (somMethodPtr) 

A pointer to the location in memory where a pointer to the specified method's procedure should be stored. Both methods store a 
NULL pointer in this location (if the method does not exist) or a value that can be called. 

rc (boolean) 



TRUE 

FALSE 



Returns TRUE when the method procedure can be called directly and FALSE when the method 
procedure is a dispatch function. 

Returns FALSE when the method procedure is a dispatch function. 



somFindMethodOk - Remarks 



This method performs name-lookup method resolution, determines the method procedure appropriate for performing the indicated method 
on instances of the receiving class, and loads m with the method procedure address. For static methods, method procedure resolution is 
done using the instance method table of the receiving class. 

Name-lookup resolution must be used to invoke dynamic methods. Also, name-lookup can be useful when different classes introduce 
methods of the same name, signature, and desired semantics, but it is not known until runtime which of these classes should be used as a 
type for the objects on which the method is to be invoked. If the signature of a method is a not known, then method procedures cannot be be 
used directly, and the somDispatch method can be used after dynamically discovering the signature to allow the correct arguments can be 
placed on a vajist. 

As with any method that returns procedure pointers, this method allows repeated invocations of the same method procedure to be 
programmed. If this is done, it up to the programmer to prevent runtime errors by assuring that each invocation is performed either on an 
instance of the class used to resolve the method procedure or of some class derived from it. Whenever using SOM method procedure 
pointers, it is necessary to indicate the arguments to be passed and the use of system linkage to the compiler, so it can generate a correct 
procedure call. The way this is done depends on the compiler and the system being used. Flowever, C and C++ usage bindings provide an 
appropriate typedef for static methods. The name of the typedef is based on the name of the class that introduces the method, as illustrated 
in the example below. 

Unlike the somFindMethod method, if the class does not support the specified method, the somFindMethodOk method raises an error 
and halts execution. 

If the class does not support the specified method, then * m is set to NULL and the return value is meaningless. Otherwise, the returned 
result is true if the indicated method was a static method. 



somFindMethodOk - Original Class 

SOMCIass 



somFindMethodOk - Related Methods 



Methods 



somFindSMethod 

somFindSMethodOK 

somSupportsMethod 




somDispatch, 

somClassDispatch 



Functions 



• somApply 

• som Resolve 

• somClassResolve 

• somResolveByName 

• somParentNumResolve 



Macros 



SOMResolve 

SOMResolveNoCheck 

SOMParentNumResolve 



somFindMethodOk - Example Code 



Assuming that the An/ma/ class introduces the method setSound , the type name for the setSound method procedure type will be 
somTD_An/ma/_setSound , as illustrated in the Example. 

#include <animal.h> 
void main ( ) 

{ 

An ima 1 myAn ima 1 ; 
somld somId_setSound; 
somTD_Animal_set Sound methodPtr; 

Environment *ev = somGetGlobalEnvironment ( ) ; 

myAnimal = AnimalNew(); 

/* 

Note: Next three lines are equivalent to 
_setSound (myAnimal , ev, "Roar! ! ! " ) ; 

*/ 

somId_setSound = somldFromString ( "setSound" ) ; 

_somFindMethod (_somGetClass (myAnimal) , 

somId_setSound, &methodPtr) ; 
methodPtr (myAnimal, ev, "Roar! ! ! ") ; 

/* */ 

_display (myAnimal , ev) ; 

_somFree (myAnimal) ; 



/* 

Program Output: 
This Animal says 
Roar! ! ! 

*/ 



somFindMethodOk - Topics 



Select an item: 
Syntax 
Parameters 
Returns 
Remarks 
Original Class 
Example Code 
Related Methods 



Glossary 



so m FindS Method 



somFindSMethod - Syntax 



This method finds the method procedure for a static method. Not generally overridden. 
For backward compatibility, this method does not take an Environment parameter. 



SOMClass receiver; 
somld methodld; 
somMethodPtr rc; 

rc = somFindSMethod (receiver , methodld); 



somFindSMethod Parameter - receiver 



receiver (SOMClass) 

A pointer to a class object. 



somFindSMethod Parameter - methodld 



methodld (somld) 

A somld representing the name of the desired method. 



somFindSMethod Parameter - rc 



rc (somMethodPtr) 



This method returns a pointer to the method procedure that supports the specified method for the class. 



so m FindS Method - Parameters 



receiver (SOMCIass) 

A pointer to a class object. 

methodld (somld) 

A somld representing the name of the desired method, 
rc (somMethodPtr) 



This method returns a pointer to the method procedure that supports the specified method for the class. 



somFindSMethod - Remarks 



This method performs name-lookup resolution in a similar fashion to somFindMethod and somFindMethodOK, but are restricted to static 
but is restricted to static methods. See the description of somFindMethod for a discussion of name-lookup method resolution. Because this 
method is restricted to resolving static methods, its interface is slightly different from the somFindMethod interface; a method procedure 
pointer is returned when lookup is successful; otherwise NULL is returned. 

The somFindSMethodOk method is identical to this method except that, with somFindSMethodOk, an error is raised if the indicated static 
method is not defined for the receiving class, and execution is halted. 



somFindSMethod - Original Class 



SOMCIass 



somFindSMethod - Related Methods 



Methods 

• somFindMethod 

• somFindMethodOk 



somFindSMethod - Example Code 



See the somFindMethod method example. 




so m Finds Method - Topics 
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somFindSMethodOk 



somFindSMethodOk - Syntax 



This method finds the method procedure for a static method. Not generally overridden. 
For backward compatibility, this method does not take an Environment parameter. 



SOMClass receiver; 
somld methodld; 
somMethodPtr rc; 

rc = somFindSMethodOk (receiver , methodld); 



somFindSMethodOk Parameter - receiver 



receiver (SOMClass) 

A pointer to a class object. 



somFindSMethodOk Parameter - methodld 



methodld (somld) 

A somld representing the name of the desired method. 



somFindSMethodOk Parameter - rc 



rc (somMethodPtr) 



This method returns a pointer to the method procedure that supports the specified method for the class. 



somFindSMethodOk - Parameters 

receiver (SOMCIass) 

A pointer to a class object. 

methodld (somld) 

A somld representing the name of the desired method, 
rc (somMethodPtr) 

This method returns a pointer to the method procedure that supports the specified method for the class. 



somFindSMethodOk - Remarks 



This method performs name-lookup resolution in a similar fashion to somFindMethod and somFindMethodOK, but are restricted to static 
but is restricted to static methods. See the description of somFindMethod for a discussion of name-lookup method resolution. Because this 
method is restricted to resolving static methods, its interface is slightly different from the somFindMethod interface; a method procedure 
pointer is returned when lookup is successful; otherwise NULL is returned. 

This method is identical to somFindSMethod, except that an error is raised if the indicated static method is not defined for the receiving 
class, and execution is halted. 



somFindSMethodOk - Original Class 



SOMCIass 



somFindSMethodOk - Related Methods 



Methods 

• somFindMethod 

• somFindMethodOk 




somFindSMethodOk - Example Code 



See the somFindMethod method example . 



somFindSMethodOk - Topics 



Select an item: 
Syntax 
Parameters 
Returns 
Remarks 
Original Class 
Example Code 
Related Methods 
Glossary 



somGetlnstancePartSize 



somGetlnstancePartSize - Syntax 



This method returns the total size of the instance data structure introduced by a class. Not generally overridden. 
For backward compatibility, this method does not take an Environment parameter. 



SOMClass receiver; 

long rc; 

rc = somGetlnstancePartSize (receiver) ; 



somGetlnstancePartSize Parameter - receiver 



receiver (SOMClass) 



A pointer to the class object whose instance data size is desired. 



somGetlnstancePartSize Parameter - rc 



rc (long) 



bytes 

0 



Returns the size, in bytes, of the instance variables introduced by this class. This does not include 
the size of instance variables introduced by this class's ancestor or descendent classes. 

Returns 0 if a class introduces no instance variables. 



somGetlnstancePartSize - Parameters 

receiver (SOMCIass) 

A pointer to the class object whose instance data size is desired, 
rc (long) 



bytes 

0 



Returns the size, in bytes, of the instance variables introduced by this class. This does not include 
the size of instance variables introduced by this class's ancestor or descendent classes. 

Returns 0 if a class introduces no instance variables. 



somGetlnstancePartSize - Remarks 



This method returns the amount of space needed in an object of the specified class or any of its subclasses to contain the instance variables 
introduced by the class. 



somGetlnstancePartSize - Original Class 



SOMCIass 



somGetlnstancePartSize - Related Methods 



Methods 



somGetlnstanceSize 




somGetlnstancePartSize - Example Code 



#include <animal.h> 
main ( ) 

{ 

An ima 1 my An ima 1 ; 

SOMClass animalClass; 
int instanceSize; 
int instanceOf f set ; 
int instancePartSize; 

my Animal = AnimalNew (); 
animalClass = _somGetClass (myAnimal) ; 
instanceSize = _somGetInstanceSize (animalClass) ; 
instanceOf f set = _somGetInstanceOf f set (animalClass) ; 
instancePartSize = _somGetInstancePartSize (animalClass) ; 
somPrintf ("Instance Size: %d\n", instanceSize); 
somPrintf ("Instance Offset: %d\n", instanceOf f set ) ; 
somPrintf ("Instance Part Size: %d\n", instancePartSize); 
_somFree (myAnimal) ; 



/* 

Output from this program: 
Instance Size: 8 
Instance Offset: 0 
Instance Part Size: 4 
*/ 



somGetlnstancePartSize - Topics 



Select an item: 
Syntax 
Parameters 
Returns 
Remarks 
Original Class 
Example Code 
Related Methods 
Glossary 



somGetlnstanceSize 



somGetlnstanceSize - Syntax 



This method returns the size of an instance of a class. Not generally overridden. 



For backward compatibility, this method does not take an Environment parameter. 



SOMClass receiver; 

long rc; 

rc = somGetlnstanceSize (receiver) ; 



somGetlnstanceSize Parameter - receiver 



receiver (SOMClass) 

A pointer to the class object whose instance size is desired. 



somGetlnstanceSize Parameter - rc 



rc (long) 



bytes Returns the size, in bytes, of each instance of this class. This includes the space required for 

instance variables introduced by this class and all of its ancestor classes. 



somGetlnstanceSize - Parameters 



receiver (SOMClass) 

A pointer to the class object whose instance size is desired, 
rc (long) 



bytes Returns the size, in bytes, of each instance of this class. This includes the space required for 

instance variables introduced by this class and all of its ancestor classes. 



somGetlnstanceSize - Remarks 



This method returns the total amount of space needed in an instance of the specified class. 



somGetlnstanceSize - Original Class 



SOMCIass 



somGetlnstanceSize - Related Methods 



Methods 



somGetlnstancePartSize 



somGetlnstanceSize - Example Code 



#include <animal.h> 
main ( ) 

{ 

An ima 1 myAn ima 1 ; 

SOMCIass animalClass; 
int instanceSize; 
int instanceOf f set ; 
int instancePartSize; 

myAnimal = AnimalNew (); 
animalClass = _somGetClass (myAnimal) ; 
instanceSize = ^somGetlnstanceSize (animalClass) ; 
instanceOf f set = _somGetInstanceOf f set (animalClass) ; 
instancePartSize = _somGetInstancePartSize (animalClass) ; 
somPrintf ("Instance Size: %d\n", instanceSize); 
somPrintf ("Instance Offset: %d\n", instanceOf f set ) ; 
somPrintf ("Instance Part Size: %d\n", instancePartSize); 
_somFree (myAnimal) ; 



/* 

Output from this program: 
Instance Size: 8 
Instance Offset: 0 
Instance Part Size: 4 
*/ 



somGetlnstanceSize - Topics 



Select an item: 
Syntax 
Parameters 
Returns 
Remarks 
Original Class 
Example Code 
Related Methods 
Glossary 



somGetlnstanceToken 



somGetlnstanceToken - Syntax 



This method returns a data access token for the instance data introduced by a class. 
For backward compatibility, this method does not take an Environment parameter. 

SOMClass receiver; 

somDToken rc; 

rc = somGetlnstanceToken (receiver) ; 



somGetlnstanceToken Parameter - receiver 



receiver (SOMClass) 

A pointer to a SOMClass object. 



somGetlnstanceToken Parameter - rc 



rc (somDToken) 



Returns a data token for the beginning of the instance data introduced by the receiver. 



somGetlnstanceToken - Parameters 



receiver (SOMClass) 

A pointer to a SOMClass object. 

rc (somDToken) 



Returns a data token for the beginning of the instance data introduced by the receiver. 



somGetlnstanceToken - Remarks 



This method returns a data token "pointing" to the beginning of the instance data introduced by the receiving class. This token can be 
passed to the function somDataResolve to locate this instance data within an an instance of the receiver class or any class derived from it. 
Also the instance data token for a class can be passed to the class method somGetMemberToken to get a data token for a specific 
instance variables introduced by the class (if the relative offset of this instance variable is known). This approach is used by C and C++ 
implementation bindings to support public instance data for OIDL classes (IDL classes currently have no public instance data). 

A data token for the instance data introduced by a class is required by method procedures that access data introduced by the method 
procedure's defining class. For classes declared using OIDL and IDL, the needed token is stored in the auxiliary class data structure, which 
is an external data structure made statically available by the C and C++ language bindings as <className>CCIassData.instanceToken. 
Thus, this method call is not generally used by C and C++ class implementors of classes declared using OIDL or IDL. 



somGetlnstanceToken - Original Class 



SOMCIass 



somGetlnstanceToken - Related Methods 



Functions 



somDataResolve 



Methods 



somGetlnstanceSize 

somGetlnstancePartSize 

somGetMemberToken 



somGetlnstanceToken - Topics 



Select an item: 
Syntax 
Parameters 
Returns 
Remarks 
Original Class 
Related Methods 
Glossary 



somGetMemberToken 



somGetMemberToken - Syntax 



This method returns an access token for an instance variable. This method is not generally overridden. 
For backward compatibility, this method does not take an Environment parameter. 



SOMClass 

long 

somDToken 

somDToken 



receiver; 
memberOf f set ; 
instanceToken; 
rc; 



rc = somGetMemberToken (receiver, memberOf f set , 
instanceToken) ; 



somGetMemberToken Parameter - receiver 



receiver (SOMClass) 

A pointer to a SOMClass object. 



somGetMemberToken Parameter - memberOffset 



memberOffset (long) 

A 32-bit integer representing the offset of the required data member. 



somGetMemberToken Parameter - instanceToken 



instanceToken (somDToken) 

A token, obtained from somGetlnstanceToken, that identifies the introduced portion of the class. 



somGetMemberToken Parameter - rc 



rc (somDToken) 



Returns an access token for the specified data member. 



somGetMemberToken - Parameters 



receiver (SOMCIass) 

A pointer to a SOMCIass object. 

memberOffset (long) 

A 32-bit integer representing the offset of the required data member. 

instanceToken (somDToken) 

A token, obtained from somGetlnstanceToken, that identifies the introduced portion of the class, 
rc (somDToken) 



Returns an access token for the specified data member. 



somGetMemberToken - Remarks 



This method returns an access token for the data member at offset memberOffset within the block of instance data identified by instance 
token. The returned token can subsequently be passed to the somDataResolve function to locate the data member. 

Typically, only the code that implements a class declared using OIDL requires access to this method, and this code is normally provided by 
implementation bindings. Thus C and C++ programmers do not normally invoke this method. 



somGetMemberToken - Original Class 



SOMCIass 



somGetMemberToken - Related Methods 



Functions 



somDataResolve 



Methods 



somGetlnstanceSize 

somGetlnstancePartSIze 

somGetlnstanceToken 



somGetMemberToken - Topics 



Select an item: 

Syntax 

Parameters 

Returns 

Remarks 



Original Class 
Related Methods 
Glossary 



somGetMethodData 



somGetMethodData - Syntax 



This method returns method information for a specified method, which must have been introduced by the receiver class or an ancestor of 
that class. Not generally overridden. 

For backward compatibility, this method does not take an Environment parameter. 



SOMClass receiver; 

somld methodld; 

somMethodData md; 
boolean rc; 

rc = somGetMethodData (receiver, methodld, 
md) ; 



somGetMethodData Parameter - receiver 



receiver (SOMClass) 

A pointer to the class that produced the index value. 



somGetMethodData Parameter - methodld 



methodld (somld) 

A somld for the method's name. 



somGetMethodData Parameter - md 



md (somMethodData) 

A pointer to a somMethodData structure. 



somGetMethodData Parameter - rc 



rc (boolean) 



Returns boolean true if successful. 
Returns false if not successful. 



true 

false 



somGetMethodData - Parameters 



receiver (SOMCIass) 

A pointer to the class that produced the index value. 

methodld (somld) 

A somld for the method's name. 

md (somMethodData) 

A pointer to a somMethodData structure. 

rc (boolean) 



true Returns boolean true if successful, 

false Returns false if not successful. 



somGetMethodData - Remarks 



This method loads a somMethodData structure with data describing the method identified by the passed method/d. If method/d does not 
identify a method known to the receiver, then false is returned; otherwise, true is returned after loading the somMethodData structure with 
data corresponding to the indicated method. 



somGetMethodData - Original Class 

SOMCIass 



somGetMethodData - Related Methods 



Data Structures 




somMethodData (somapi.h) 



Methods 



somGetMethodlndex 

somGetMethodData 

somGetNthMethodlnfo 



somGetMethodData - Example Code 



#include <somcls.xh> 

main 

{ 

somEnvironmentNew ( ) ; 

somld gmild = somldFromString ( "somGetMethodlndex" ) ; 
somMethodData md; 

boolean rc = _SOMClass->somGetMethodData (gmild, &md) ; 
SOM_Test (rc && somComparelds (gmild, md.id); 

} 



somGetMethodData - Topics 



Select an item: 
Syntax 
Parameters 
Returns 
Remarks 
Original Class 
Example Code 
Related Methods 
Glossary 



somGetMethodDescriptor 



somGetMethodDescriptor - Syntax 



This method returns the method descriptor for a method. Not generally overridden. 
For backward compatibility, this method does not take an Environment parameter. 



SOMClass receiver; 
somld methodld; 
somld rc; 

rc = somGetMethodDescriptor (receiver, methodld); 



somGetMethodDescriptor Parameter - receiver 



receiver (SOMClass) 

A pointer to a SOMClass. 



somGetMethodDescriptor Parameter - methodld 



methodld (somld) 

A somld method descriptor. 



somGetMethodDescriptor Parameter - rc 



rc (somld) 



Returns a somld method descriptor. 



somGetMethodDescriptor - Parameters 



receiver (SOMClass) 

A pointer to a SOMClass. 



methodld (somld) 

A somld method descriptor. 



rc (somld) 



Returns a somld method descriptor. 



somGetMethodDescriptor - Remarks 



This method returns the method descriptor for a specified method of a class. (A method descriptor is a somld that represents the identifier of 
an attribute definition or a method definition in the SOM Interface Repository. It contains information about the method's return type and the 
types of its arguments.) If the class object does not support the indicated method, NULL is returned. 



somGetMethodDescriptor - Original Class 



SOMCIass 



somGetMethodDescriptor - Related Methods 



Methods 



somAddDynamicMethod 

somGetNthMethodlnfo 

somGetMethodData 

somGetNthMethodData 



somGetMethodDescriptor - Example Code 



somld myMethodDescriptor ; 

myMethodDescriptor = _somGetMethodDescriptor (_Animal, 

somldFromString ( " setSound" ) ) ; 



somGetMethodDescriptor - Topics 



Select an item: 
Syntax 
Parameters 
Returns 
Remarks 
Original Class 
Example Code 
Related Methods 
Glossary 



somGetMethodlndex 



so m Get Method Index - Syntax 



This method returns a class-specific index for a method. Not generally overridden. 
For backward compatibility, this method does not take an Environment parameter. 



SOMClass receiver; 
somld methodld; 
long rc; 

rc = somGetMethodlndex (receiver, methodld); 



somGetMethodlndex Parameter - receiver 



receiver (SOMClass) 

A pointer to a SOMClass object. 



somGetMethodlndex Parameter - methodld 



methodld (somld) 

A somld method ID. 



somGetMethodlndex Parameter - rc 



rc (long) 



Returns a positive long if successful. 
Returns a -1 if not successful. 



long 

-1 



somGetMethodlndex - Parameters 



receiver (SOMClass) 

A pointer to a SOMClass object. 



methodld (somld) 



A somld method ID. 



rc (long) 



Returns a positive long if successful. 
Returns a -1 if not successful. 



long 

-1 



somGetMethodlndex - Remarks 



This method returns an index that can be used in subsequent calls to the same receiving class to determine information about the indicated 
(static or dynamic) method, via the methods somGetNthMethodData and somGetNthMethodlnfo. The method must be appropriate for 
use on an instance of the receiver class; otherwise, a -1 is returned. The index of a method can change over time if dynamic methods are 
added to the receiver class or its ancestors. Thus, in dynamic multi-threaded environments, a critical region should be used to bracket the 
use of this method and of subsequent requests for method information based on the returned index. 



somGetMethodlndex - Original Class 



SOMCIass 



somGetMethodlndex - Related Methods 



Data Structures 

• somMethodData (somapi.h) 



Methods 



somGetNthMethodData 

somGetNthMethodlnfo 



somGetMethodlndex - Example Code 



#include <somcls.xh> 
main 
{ 

somEnvironmentNew ( ) ; 

somld gmild = somldFromString ( "somGetMethodlndex" ) ; 
long index = _SOMClass->somGetMethodIndex (gmild) ; 
somMethodData md; 

boolean rc = _SOMClass->somGetNthMethodData (index, &md) ; 
SOM_Test (rc && somComparelds (gmild, md.id)); 




so m Get Method Index - Topics 



Select an item: 
Syntax 
Parameters 
Returns 
Remarks 
Original Class 
Example Code 
Related Methods 
Glossary 



somGetMethodT oken 



somGetMethodToken - Syntax 



This method returns a method access token for static method. Not generally overridden. 
For backward compatibility, this method does not take an Environment parameter. 



SOMClass receiver; 
somld methodld; 
somMToken rc; 

rc = somGetMethodToken (receiver , methodld); 



somGetMethodToken Parameter - receiver 



receiver (SOMClass) 

A pointer to a SOMClass object. 



somGetMethodToken Parameter - methodld 



methodld (somld) 

A somld identifying a method. 



somGetMethodToken Parameter - rc 



rc (somMToken) 



Returns a somMToken method access token. 



somGetMethodToken - Parameters 

receiver (SOMCIass) 

A pointer to a SOMCIass object. 

methodld (somld) 

A somld identifying a method. 

rc (somMToken) 

Returns a somMToken method access token. 



somGetMethodToken - Remarks 



This method returns a method access token for a static method with the specified id that was introduced by the receiver class or an ancestor 
of the receiver class. This method token can be passed to the somResolve function (or one of the other offset-based method resolution 
functions) to select a method procedure pointer from a method table of an object whose class is the same as, or is derived from the class 
that introduced the method. 

The example below assumes that the class An/ma/ introduces the method setSound. 



somGetMethodToken - Original Class 



SOMCIass 



somGetMethodToken - Related Methods 



Functions 

• somResolve 

• somClassResolve 

• somParentNumResolve 




Methods 



somGetNthMethodlnfo 

somGetMethodData 



somGetMethodToken - Example Code 



#include < > 
main() { 
somMToken tok; 

An ima 1 myAn ima 1 ; 

somTD_Animal_setSound methodPtr; /* use typedef from animal. h */ 
Environment *ev = somGetGlobalEnvironment ( ) ; 
myAnimal = AnimalNew(); 

/* next 3 lines equivalent to _setSound (myAnimal, ev, "Roar! ! ! " ) ; 
tok = _ somGetMethodToken (_An ima 1, somldFromString ( " setSound" ) ) ; 
methodPtr = (somTD_Animal_setSound) somResolve (myAnimal, tok); 
methodPtr (myAnimal , ev, "Roar! ! !"); 

_display (myAnimal , ev) ; 

_somFree (myAnimal) ; 

} 



somGetMethodToken - Topics 



Select an item: 
Syntax 
Parameters 
Returns 
Remarks 
Original Class 
Example Code 
Related Methods 
Glossary 



somGetname 



somGetname - Syntax 



This method returns the name of a class. Not generally overridden. 



For backward compatibility, this method does not take an Environment parameter. 



SOMClass receiver; 

string rc; 

rc = somGetname (receiver) ; 



somGetname Parameter - receiver 



receiver (SOMClass) 

The class whose name is desired. 



somGetname Parameter - rc 



rc (string) 

Returns a pointer to the name of the class. 



somGetname - Parameters 



receiver (SOMClass) 

The class whose name is desired. 

rc (string) 

Returns a pointer to the name of the class. 



somGetname - Remarks 



This method returns the address of a zero-terminated string that gives the name of the receiving class. This name may be used as a 
Repositoryld in the Repositoryjookupjd method (described in the SOM Interface Repository Framework section) to obtain the IDL 
interface definition that corresponds to the receiving class. 

The returned name is not necessarily the same as the statically known class name used by a programmer to gain access to the class object 
(e.g., via the method somFindClass). This is because the method somSubstituteClass may have been used to "shadow" the class having 
the static name used by the programmer. 

Also, when the interface to a class's instances is defined within an IDL module, the returned name will not directly correspond to the names 
of the procedures and macros made available by C and C++ usage bindings for accessing class objects (e.g., the <className>NewClass 
procedure, or the _<className> macro). This is because the token used in constructing the names of these procedures and macros uses 
an underscore character to separate the module name from the interface name, while the actual name of the corresponding class uses two 
colon characters instead of an underscore for this purpose. 

This method is not generally overridden. The returned address is valid until the class object is unregistered or freed. 



somGetname - Original Class 



SOMCIass 



somGetname - Related Methods 



Methods 



Repositorylookupjd 

somSubstituteClass 

somFindClass 



somGetname - Example Code 



#include <animal.h> /* assume Animal defined in th e Zoo module */ 

#include <string.h> 
main ( ) 

{ 

string className = Zoo_AnimalNewClass ( 0 , 0 ) ->somGetName ( ) ; 

SOM_Test ( ! strcmp ( className, " Zoo :: Animal" )) ; 

} 



somGetname - Topics 



Select an item: 
Syntax 
Parameters 
Returns 
Remarks 
Original Class 
Example Code 
Related Methods 
Glossary 



somGetNthMethodData 



somGetNthMethodData - Syntax 



This method returns method information for the /7th (static or dynamic) method known to a given class. Not generally overridden. 
For backward compatibility, this method does not take an Environment parameter. 



SOMClass receiver; 

long index; 

somMethodData md; 

boolean rc; 

rc = somGetNthMethodData (receiver, index, 
md) ; 



somGetNth Method Data Parameter - receiver 



receiver (SOMClass) 

A pointer to the class that produced the index value. 



somGetNthMethodData Parameter - index 



index (long) 

An index returned as a result of a previous call of somGetMethodlndex. 



somGetNthMethodData Parameter - md 



md (somMethodData) 

A pointer to a somMethodData structure. 



somGetNthMethodData Parameter - rc 



rc (boolean) 



Returns boolean true if successful. 
Returns false if not successful. 



true 

false 



somGetNthMethodData - Parameters 



receiver (SOMCIass) 

A pointer to the class that produced the index value, 
index (long) 

An index returned as a result of a previous call of somGetMethodlndex. 

md (somMethodData) 

A pointer to a somMethodData structure. 

rc (boolean) 



true Returns boolean true if successful, 

false Returns false if not successful. 



somGetNth Method Data - Remarks 



This method loads a somMethodData structure with data describing the method identified by the passed index. The index must have been 
produced by a previous call to exactly the same receiver class; the same method will in general have different indexes in different classes. If 
the index does not identify a method known to this class, then false is returned; otherwise, true is returned after loading the somMethodData 
structure with data corresponding to the indicated method. 



somGetNthMethodData - Related Methods 



Data Structures somMethodData (somapi.h) 

Methods 



somGetMethodlndex 

somGetMethodData 

somGetNthMethodlnfo 



somGetNthMethodData - Example Code 



#include <somcls.xh> 
main 
{ 

somEnvironmentNew ( ) ; 

somld gmild = somldFromString ( "somGetMethodlndex" ) ; 
long index = _SOMClass->somGetMethodIndex (gmild) ; 
somMethodData md; 

boolean rc = _SOMClass->somGetNthMethodData (index, &md) ; 
SOM_Test (rc && somComparelds (gmild, md.id)); 




somGetNth Method Data - Topics 



Select an item: 
Syntax 
Parameters 
Returns 
Remarks 
Example Code 
Related Methods 
Glossary 



somGetNthMethodlnfo 



somGetNthMethodlnfo - Syntax 



This method returns the somld of the /7th (static or dynamic) method known to a given class. Also loads a somld with a descriptor for the 
method. Not generally overridden. 

For backward compatibility, this method does not take an Environment parameter. 



SOMClass 

long 

somld 

somld 



receiver; 

index; 

descriptor; 

rc; 



rc = somGetNthMethodlnfo (receiver , index, 
descriptor) ; 



somGetNthMethodlnfo Parameter - receiver 



receiver (SOMClass) 

A pointer to the class from which the index was obtained using method somGetMethodlndex. 



somGetNthMethodlnfo Parameter - index 



index (long) 

The /7th method known to this class, whose method descriptor is desired. 



somGetNthMethodlnfo Parameter - descriptor 



descriptor (somld) 

A pointer to a somld that will be loaded with a somld for the descriptor. 



somGetNthMethodlnfo Parameter - rc 



rc (somld) 



somID 

NULL 



Returns the somld for the indicated method, if a method with the indicated index is known to the 
receiver. 

Returns NULL if a method with the indicated index is not known to the receiver. 



somGetNthMethodlnfo - Parameters 



receiver (SOMCIass) 

A pointer to the class from which the index was obtained using method somGetMethodlndex. 
index (long) 

The /7th method known to this class, whose method descriptor is desired. 

descriptor (somld) 

A pointer to a somld that will be loaded with a somld for the descriptor, 
rc (somld) 



somID Returns the somld for the indicated method, if a method with the indicated index is known to the 

receiver. 

NULL Returns NULL if a method with the indicated index is not known to the receiver. 



somGetNthMethodlnfo - Remarks 



This method returns the identifier of a method, and loads the somld whose address is passed with the somld of the method descriptor. 
Method descriptors are used to support access to information stored in a SOM Interface Repository. 



somGetNthMethodlnfo - Original Class 




SOMCIass 



somGetNthMethodlnfo - Related Methods 



Classes 

• Repository (repostry.idl) 

Methods 



somGetMethodlndex 

somGetNthMethodData 



somGetNthMethodlnfo - Example Code 



#include <somcls.xh> 
main ( ) 

{ 

somEnvironmentNew ( ) ; 

somld descriptor, icld = somldFromSring ( "somGetMethodlndex" ) ; 
long ndx = _SOMClass->somGetMethodIndex (icld) ; 
somMethodData md; 

boolean rc = _SOMClass->somGetNthMethodData ( index, &md) ; 
SOM_Test (rc && somComparelds (gmild, md.id)); 

} 



somGetNthMethodlnfo - Topics 



Select an item: 
Syntax 
Parameters 
Returns 
Remarks 
Original Class 
Example Code 
Related Methods 
Glossary 



somGetNumMethods 



somGetNumMethods - Syntax 



This method returns the number of methods available for a class of objects. Not generally overridden. 
For backward compatibility, this method does not take an Environment parameter. 



SOMClass receiver; 

long rc; 

rc = somGetNumMethods (receiver) ; 



somGetNumMethods Parameter - receiver 



receiver (SOMClass) 

A pointer to the class object whose instance method count is desired. 



somGetNumMethods Parameter - rc 



rc (long) 

Returns the total number of methods that are currently available for the receiving class. 



somGetNumMethods - Parameters 



receiver (SOMClass) 

A pointer to the class object whose instance method count is desired, 
rc (long) 

Returns the total number of methods that are currently available for the receiving class. 



somGetNumMethods - Remarks 



This method returns the number of methods currently supported by the specified class, including inherited methods (both static and 
dynamic). 

The value that this method returns is the total number of methods currently known to the receiving class as being applicable to its instances. 
This includes both static and dynamic methods, whether defined in this class or inherited from an ancestor class. 



somGetNumMethods - Original Class 



SOMCIass 



somGetNumMethods - Related Methods 



Methods 



somGetNumStaticMethods 



somGetNumMethods - Example Code 



#include <animal.h> 
main ( ) 

{ 

long numMethods; 



AnimalNewClass (Animal_Ma jorVersion, Animal_MinorVersion) ; 

numMethods = _somGetNumMethods (_Animal) ; 

somPrintf ( "Number of methods supported by class: %d\n", 

numMethods) ; 



somGetNumMethods - Topics 



Select an item: 
Syntax 
Parameters 
Returns 
Remarks 
Original Class 
Example Code 
Related Methods 
Glossary 



somGetNumStaticMethods 



somGetNumStaticMethods - Syntax 



This method obtains the number of static methods available for a class of objects. Not generally overridden. 
For backward compatibility, this method does not take an Environment parameter. 



SOMClass receiver; 

long rc; 

rc = somGetNumStaticMethods (receiver) ; 



somGetNumStaticMethods Parameter - receiver 



receiver (SOMClass) 

A pointer to the class object whose static method count is desired. 



somGetNumStaticMethods Parameter - rc 



rc (long) 

Returns the total number of static methods that are available for instances of the receiving class. 



somGetNumStaticMethods - Parameters 



receiver (SOMClass) 

A pointer to the class object whose static method count is desired, 
rc (long) 

Returns the total number of static methods that are available for instances of the receiving class. 



somGetNumStaticMethods - Remarks 



This method returns the number of static methods available in the specified class, including inherited ones. Static methods are those that 
are represented by entries in the class's instance method table, and which can be invoked using method tokens and offset resolution. 



somGetNumStaticMethods - Original Class 



SOMCIass 



somGetNumStaticMethods - Related Methods 



Methods 



somGetNumMethods 



somGetNumStaticMethods - Example Code 



#include <animal.h> 
main ( ) 

{ 

long numMethods; 



AnimalNewClass (Animal_Ma jorVersion, Animal_MinorVersion) ; 
numMethods = _s omGetNumS tat icMet hods (_Animal) ; 

somPrintf ( "Number of static methods supported by class: %d\n", 
numMethods) ; 



somGetNumStaticMethods - Topics 



Select an item: 
Syntax 
Parameters 
Returns 
Remarks 
Original Class 
Example Code 
Related Methods 
Glossary 



somGetParents 



somGetParents - Syntax 



This method gets a pointer to a class's parent (direct base) classes. Not generally overridden. Note: For backward compatibility, this method 
does not take an Environment parameter. 



SOMObject receiver; 

SOMClassSequence rc; 

rc = somGetParents (receiver) ; 



somGetParents Parameter - receiver 

receiver (SOMObject) 

A pointer to the class whose parent (base) classes are desired. 



somGetParents Parameter - rc 



rc (SOMClassSequence) 

The somGetParents method returns a sequence of pointers to the parents of the receiver, or NULL otherwise (in the case of 
SOMObject). The sequence of parents is in left-to-right order. 



somGetParents - Parameters 



receiver (SOMObject) 

A pointer to the class whose parent (base) classes are desired. 



rc (SOMClassSequence) 

The somGetParents method returns a sequence of pointers to the parents of the receiver, or NULL otherwise (in the case of 
SOMObject). The sequence of parents is in left-to-right order. 



somGetParents - Remarks 



The somGetparents method returns a sequence containing pointers to the parents of the receiver. 



somGetParents - Original Class 



SOMCIass 



somGetParents - Related Methods 



Methods 



somGetClass 



somGetParents - Example Code 



/* Note: Dog is a single-inheritance subclass of Animal. * 
#include <dog.idl> 
main () 

{ 

Dog myDog; 

SOMClass dogClass; 

SOMClassSequence parents; 
char *parentName; 
int i ; 

myDog = DogNew ( ) ; 
dogClass = _somGetClass (myDog) ; 
parents = _somGetPaarents (dogClass) ; 
for (i=0; i<parents ._length; i++) 

somprintf(" — parent %d is %s\n", i; 

_somGetName (parents ._buf fer [i] ) ) ; 

_somFree (myDog) ; 



/* 

Output from this program: 
— parent 0 is Animal 
*/ 



somGetParents - Topics 



Select an item: 
Syntax 
Parameters 
Returns 
Remarks 
Original Class 
Example Code 
Related Methods 
Glossary 



somGetVersionNumbers 



somGetVersionNumbers - Syntax 



This method gets the major and minor version numbers of a class. Not generally overridden. 
For backward compatibility, this method does not take an Environment parameter. 



SOMClass receiver; 

long ma jorVersion; 

long minorVersion; 

somGetVersionNumbers (receiver, ma jorVersion, 
minorVersion) ; 



somGetVersionNumbers Parameter - receiver 



receiver (SOMClass) 

A pointer to a class object. 



somGetVersionNumbers Parameter - majorVersion 



majorVersion (long) 

A pointer where the major version number is to be stored. 



somGetVersionNumbers Parameter - minorVersion 



minorVersion (long) 

A pointer where the minor version number is to be stored. 



somGetVersionNumbers Parameter - rc 



rc 



somGetVersionNumbers - Parameters 



receiver (SOMCIass) 

A pointer to a class object. 

majorVersion (long) 

A pointer where the major version number is to be stored. 

minorVersion (long) 

A pointer where the minor version number is to be stored. 



rc 



somGetVersionNumbers - Remarks 



This method returns, via its output parameters, the major and minor version numbers of the class specified by receiver. The class object 
must have already been created (because the class object is the receiver of the method). 



somGetVersionNumbers - Original Class 



SOMCIass 



somGetVersionNumbers - Related Methods 



Methods 



somCheckVersion 



somGetVersionNumbers - Example Code 



#include <som.h> 
main ( ) { 

long major, minor; 

SOMCIass myClass; 

somEnvironmentNew ( ) ; 

myClass = _somFindClass (SOMClassMgrOb ject , 

somldFromString ( "Animal" ) , 0, 0) ; 
_somGetVersionNumbers (myClass, &major, &minor) ; 




somPrintf ( "The version numbers are %i and %i.\n", major, minor); 



somGetVersionNumbers - Topics 



Select an item: 
Syntax 
Parameters 
Returns 
Remarks 
Original Class 
Example Code 
Related Methods 
Glossary 



somLookupMethod 



somLookupMethod - Syntax 



Performs name-look method resolution. Not generally overridden. 

For backward compatibility, this method does not take an Environment parameter. 



SOMClass receiver; 
somld methodld; 
somMethodPtr rc; 

rc = somLookupMethod (receiver , methodld); 



somLookupMethod Parameter - receiver 



receiver (SOMClass) 

A pointer to the class whose instance method for the indicated method is desired. 



somLookupMethod Parameter - methodld 



methodld (somld) 

A somld of the method whose method-procedure pointer is needed. 



somLookupMethod Parameter - rc 



rc (somMethodPtr) 

A pointer to the method procedure that supports the method indicated by method/d. Or, if the method is not supported by the 
receiving class, then an error is returned, and execution is halted. 



somLookupMethod - Parameters 



receiver (SOMCIass) 

A pointer to the class whose instance method for the indicated method is desired, 
methodld (somld) 

A somld of the method whose method-procedure pointer is needed, 
rc (somMethodPtr) 

A pointer to the method procedure that supports the method indicated by method/d. Or, if the method is not supported by the 
receiving class, then an error is returned, and execution is halted. 



somLookupMethod - Remarks 



The somLookupMethod method uses name-lookup resolution to return the address of the method procedure that supports the indicated 
method on instances of the receiver class. The method may be either static or dynamic. The SOM C and C++ usage bindings support 
name-lookup method resolution by invoking somLookupMethod on the class of the object on which a name-lookup method invocation is 
made. 

The somLookupMethod method is like somFindSMethodOK except that dynamic methods can also be returned. If the method is not 
supported by the receiving class, then an error is returned and execution is halted. To check the existence of a method, somFindMethod 
can be used. 

As always, in order to use a method procedure pointer such as that returned by somLookupMethod, it is necessary to typecast the 
procedure pointer so that the compiler can create the correct procedure call. This means that a programmer making explicit use of this 
method must either know the signature of the identified method, and from this create a typedef indicating system linkage and the appropriate 
argument and return types, or make use of an existing typedef provided by C or C++ usage bindings for a SOM class that introduces a static 
method with the desired signature. 



somLookupMethod - Original Class 



SOMCIass 



somLookupMethod - Related Methods 




Methods 



somFindSMethod 

somFindSMethodOk 

somFindMethod 

somFindMethodOk 



somLookupMethod - Example Code 



#include <somcls.xh> 

#include <somcm.xh> 
void main ( ) 

{ 

somld fcpld = somldFromString ( "somFindClass" ) 
somld animalld = somldFromString ( "Animal" ) ; 
SOMClassMgr *cm = somEnvironmentNew ( ) ; 
somTD_SOMClassMgr_somFindClass f indclassproc = 

( s omT D_S OMC 1 a s sMg r_s omF i ndC 1 a s s ) 

_SOMClassMgr->somLookupMethod (fcpld) ; 
SOMClass *aCls = f indclassproc (cm, animalld, 0 , 0 ) ; 

somFree (fcpld) ; 
somFree (animalld) ; 



somLookupMethod - Topics 



Select an item: 
Syntax 
Parameters 
Returns 
Remarks 
Original Class 
Example Code 
Related Methods 
Glossary 



somNew 



somNew - Syntax 



This method creates a new instance of a class. 



For backward compatibility, this method does not take an Environment parameter. 



SOMClass receiver; 

SOMObject rc; 

rc = somNew (receiver) ; 



somNew Parameter - receiver 



receiver (SOMClass) 

A pointer to the class object that is to create a new instance. 



somNew Parameter - rc 



rc (SOMObject) 

A pointer to the newly created SOMObject object, or NULL. 



somNew - Parameters 



receiver (SOMClass) 

A pointer to the class object that is to create a new instance, 
rc (SOMObject) 

A pointer to the newly created SOMObject object, or NULL. 



somNew - Remarks 



The somNew and somNewNolnit methods create a new instance of the receiving class. Space is allocated as necessary to hold the new 
object. 

When either of these methods is applied to a class, the result is a new instance of that class. If the receiver class is SOMClass or a class 
derived from SOMClass, the new object will be a class object; otherwise, the new object will not be a class object. The somNew method 
invokes the somDefaultlnit method on the newly created object. The somNewNolnit method does not. 

Either method can fail to allocate enough memory to hold a new object and, if so, NULL is returned. 

The SOM Compiler generates convenience macros for creating instances of each class, for use by C and C++ programmers. These macros 
can be used in place of this method. 



somNew - Original Class 



SOMCIass 



somNew - Related Methods 



Methods 



somRenew 



somNew - Example Code 



#include <animal.h> 

void main ( ) 

{ Animal myAnimal; 

/* 

Note: next 2 lines are functionally equivalent to 

myAnimal = AnimalNew(); 

*/ 

/* Create class object: */ 

AnimalNewClass (Animal_Ma jorVersion, AnimalMinorVersion) ; 
myAnimal = _somNew (_Animal ) ; /* Create instance of Animal els 

/* ... */ 

_somFree (myAnimal ) ; /* Free instance of Animal */ 

} 



somNew - Topics 



Select an item: 
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somNewNolnit 



somNewNolnit - Syntax 



This method creates a new instance of a class. 



For backward compatibility, this method does not take an Environment parameter. 



SOMClass receiver; 

SOMObject rc; 

rc = somNewNoInit (receiver) ; 



somNewNoInit Parameter - receiver 



receiver (SOMClass) 

A pointer to the class object that is to create a new instance. 



somNewNoInit Parameter - rc 



rc (SOMObject) 

A pointer to the newly created SOMObject object, or NULL. 



somNewNoInit - Parameters 



receiver (SOMClass) 

A pointer to the class object that is to create a new instance, 
rc (SOMObject) 

A pointer to the newly created SOMObject object, or NULL. 



somNewNoInit - Remarks 



The somNew and somNewNoInit methods create a new instance of the receiving class. Space is allocated as necessary to hold the new 
object. 

When either of these methods is applied to a class, the result is a new instance of that class. If the receiver class is SOMClass or a class 
derived from SOMClass, the new object will be a class object; otherwise, the new object will not be a class object. The somNew method 
invokes the somDefaultlnit method on the newly created object. The somNewNoInit method does not. 

Either method can fail to allocate enough memory to hold a new object and, if so, NULL is returned. 

The SOM Compiler generates convenience macros for creating instances of each class, for use by C and C++ programmers. These macros 
can be used in place of this method. 



somNewNolnit - Original Class 



SOMCIass 



somNewNolnit - Related Methods 



Methods 



somRenew 



somNewNolnit - Example Code 



#include <animal.h> 

void main ( ) 

{ Animal myAnimal; 

/* 

Note: next 2 lines are functionally equivalent to 

myAnimal = AnimalNew(); 

*/ 

/* Create class object: */ 

AnimalNewClass (Animal_Ma jorVersion, AnimalMinorVersion) ; 
myAnimal = _somNew (_Animal ) ; /* Create instance of Animal els 

/* ... */ 

_somFree (myAnimal ) ; /* Free instance of Animal */ 

} 



somNewNolnit - Topics 
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somRenew 



somRenew - Syntax 



This method creates a new object instance using a passed block of storage. 

For backward compatibility, this method does not take an Environment parameter. 



SOMClass receiver; 

somToken memPtr; 

SOMObject rc; 

rc = somRenew (receiver, memPtr); 



somRenew Parameter - receiver 



receiver (SOMClass) 

A pointer to the class object that is to create the new instance. 



somRenew Parameter - memPtr 



memPtr (somToken) 

A pointer to the space to be used to construct a new object. 



somRenew Parameter - rc 



rc (SOMObject) 

The value of newOb/ect is returned, which is now a pointer to a valid, initialized object. 



somRenew - Parameters 



receiver (SOMClass) 

A pointer to the class object that is to create the new instance. 
memPtr (somToken) 

A pointer to the space to be used to construct a new object. 



rc (SOMObject) 

The value of newOb/ect is returned, which is now a pointer to a valid, initialized object. 



somRenew - Remarks 



The somRenew method creates a new instance of the receiving class by setting the appropriate location in the passed memory block to the 
receiving class's instance method table. Unlike somNew, these "Renew" methods use the space pointed to by memPtr rather than 
allocating new space for the object. The somRenew method automatically re-initializes the object by first zeroing the object's memory, and 
then invoking somDefaultlnit; somRenewNolnit zeros memory, but does not invoke somDefaultlnit. somRenewNolnitNoZero only sets 
the method table pointer; while somRenewNoZero calls somDefaultlnit, but does not zero memory first. 

No check is made to ensure that the passed pointer addresses enough space to hold an instance of the receiving class. The caller can 
determine the amount of space necessary by using the somGetlnstanceSize method. 

The C bindings produced by the SOM Compiler contain a macro that is a convenient shorthand for somRenew (_c/ass/Vame). 



somRenew - Original Class 

SOMCIass 



somRenew - Related Methods 



Methods 



somGetlnstanceSize 

somDefaultlnit 

somNew 



somRenew - Example Code 



#include <animal.h> 

main ( ) 

{ 

void *myAnimalCluster ; 

Animal animals [5]; 

SOMCIass animalClass; 
int animalSize, i; 

animalClass = 

AnimalNewClass (Animal_Ma jorVersion, Animal_MinorVersion) ; 
animalSize = __somGetInstanceSize (animalClass) ; 

/* Round up to double-word multiple */ 
animalSize = ( (animalSize+3) /4 ) *4 ; 

/* 

* Next line allocates room for 5 objects 

* in a "cluster" with a single memory- 




* allocation operation. 

*/ 

myAnimalCluster = SOMMalloc (5*animalSize) ; 

/* 

* The for-loop that follows creates 5 initialized 

* Animal instances within the memory cluster. 

*/ 

for (i=0; i 

animals [ i ] = 

_somRenew (animalClass , myAnimalCluster+ (i*animalSize) ) ; 
/* Uninitialize the animals explicitly: */ 
for (i=0; i 

_somUninit (animals [i] ) ; 

/* 

* Finally, the next line frees all 5 animals 

* with one operation. 

*/ 

SOMFree (myAnimalCluster) ; 



somRenew - Topics 



Select an item: 
Syntax 
Parameters 
Returns 
Remarks 
Original Class 
Example Code 
Related Methods 
Glossary 



somRenewNolnit 



somRenewNolnit - Syntax 



This method creates a new object instance using a passed block of storage. 

For backward compatibility, this method does not take an Environment parameter. 



SOMClass 

somToken 

SOMObject 



receiver; 
memPtr ; 
rc; 



rc = somRenewNolnit (receiver, memPtr) ; 



somRenewNolnit Parameter - receiver 



receiver (SOMCIass) 

A pointer to the class object that is to create the new instance. 



somRenewNolnit Parameter - memPtr 



memPtr (somToken) 

A pointer to the space to be used to construct a new object. 



somRenewNolnit Parameter - rc 



rc (SOMObject) 

The value of newOb/ect is returned, which is now a pointer to a valid, initialized object. 



somRenewNolnit - Parameters 



receiver (SOMCIass) 

A pointer to the class object that is to create the new instance. 
memPtr (somToken) 

A pointer to the space to be used to construct a new object, 
rc (SOMObject) 

The value of newOb/ect is returned, which is now a pointer to a valid, initialized object. 



somRenewNolnit - Remarks 



in the passed memory block to the 
to by memPtr rather than 
zeroing the object's memory, and 

then invoking somDefaultlnit; somRenewNolnit zeros memory, but does not invoke somDefaultlnit. somRenewNolnitNoZero only sets 
the method table pointer; while somRenewNoZero calls somDefaultlnit, but does not zero memory first. 

No check is made to ensure that the passed pointer addresses enough space to hold an instance of the receiving class. The caller can 
determine the amount of space necessary by using the somGetlnstanceSize method. 

The C bindings produced by the SOM Compiler contain a macro that is a convenient shorthand for somRenew (_c/ass/Vame). 



The somRenew method creates a new instance of the receiving class by setting the appropriate location 
receiving class's instance method table. Unlike somNew, these "Renew" methods use the space pointed 
allocating new space for the object. The somRenew method automatically re-initializes the object by first 



somRenewNolnit - Original Class 




SOMCIass 



somRenewNolnit - Related Methods 



Methods 



somGetlnstanceSize 

somDefaultlnit 

somNew 



somRenewNolnit - Example Code 



#include <animal.h> 

main ( ) 

{ 

void *myAnimalCluster ; 

Animal animals [5]; 

SOMCIass animalClass; 
int animalSize, i; 

animalClass = 

AnimalNewClass (Animal_Ma jorVersion, Animal_MinorVersion) ; 
animalSize = _somGetInstanceSize (animalClass) ; 

/* Round up to double-word multiple */ 
animalSize = ( (animalSize+3) /4 ) *4 ; 

/* 

* Next line allocates room for 5 objects 

* in a "cluster" with a single memory- 

* allocation operation. 

*/ 

myAnimalCluster = SOMMalloc (5*animalSize) ; 

/* 

* The for-loop that follows creates 5 initialized 

* Animal instances within the memory cluster. 

*/ 

for (i=0; i 

animals [ i ] = 

_somRenew (animalClass, myAnimalCluster+ (i*animalSize) ) ; 

/* Uninitialize the animals explicitly: */ 
for (i=0; i 

_somUninit (animals [i] ) ; 

/* 

* Finally, the next line frees all 5 animals 

* with one operation. 

*/ 

SOMFree (myAnimalCluster) ; 



somRenewNolnit - Topics 
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somRenewNolnitNoZero 



somRenewNolnitNoZero - Syntax 



This method creates a new object instance using a passed block of storage. 

For backward compatibility, this method does not take an Environment parameter. 



SOMClass receiver; 

somToken memPtr; 

SOMObject rc; 

rc = somRenewNolnitNoZero (receiver , memPtr); 



somRenewNolnitNoZero Parameter - receiver 



receiver (SOMClass) 

A pointer to the class object that is to create the new instance. 



somRenewNolnitNoZero Parameter - memPtr 



memPtr (somToken) 

A pointer to the space to be used to construct a new object. 



somRenewNolnitNoZero Parameter - rc 



rc (SOMObject) 



The value of newObject is returned, which is now a pointer to a valid, initialized object. 



somRenewNolnitNoZero - Parameters 



receiver (SOMCIass) 

A pointer to the class object that is to create the new instance. 
memPtr (somToken) 

A pointer to the space to be used to construct a new object, 
rc (SOMObject) 

The value of newOb/ect is returned, which is now a pointer to a valid, initialized object. 



somRenewNolnitNoZero - Remarks 



The somRenew method creates a new instance of the receiving class by setting the appropriate location in the passed memory block to the 
receiving class's instance method table. Unlike somNew, these "Renew" methods use the space pointed to by memPtr rather than 
allocating new space for the object. The somRenew method automatically re-initializes the object by first zeroing the object's memory, and 
then invoking somDefaultlnit; somRenewNolnit zeros memory, but does not invoke somDefaultlnit. somRenewNolnitNoZero only sets 
the method table pointer; while somRenewNoZero calls somDefaultlnit, but does not zero memory first. 

No check is made to ensure that the passed pointer addresses enough space to hold an instance of the receiving class. The caller can 
determine the amount of space necessary by using the somGetlnstanceSize method. 

The C bindings produced by the SOM Compiler contain a macro that is a convenient shorthand for somRenew (_c/ass Name). 



somRenewNolnitNoZero - Original Class 



SOMCIass 



somRenewNolnitNoZero - Related Methods 



Methods 



somGetlnstanceSize 

somDefaultlnit 

somNew 



somRenewNolnitNoZero - Example Code 




#include <animal.h> 



main ( ) 

{ 

void *myAnimalCluster; 

Animal animals [5]; 

SOMClass animalClass; 
int animalSize, i; 

animalClass = 

AnimalNewClass (Animal_Ma jorVersion, Animal_MinorVersion) ; 
animalSize = _somGetInstanceSize (animalClass) ; 

/* Round up to double-word multiple */ 
animalSize = ( (animalSize+3) /4) *4; 

/* 

* Next line allocates room for 5 objects 

* in a "cluster" with a single memory- 

* allocation operation. 

*/ 

myAnimalCluster = SOMMalloc (5*animalSize) ; 

/* 

* The for-loop that follows creates 5 initialized 

* Animal instances within the memory cluster. 

*/ 

for (i=0; i 

animals [ i ] = 

_somRenew (animalClass, myAnimalCluster+ (i*animalSize) ) ; 

/* Uninitialize the animals explicitly: */ 
for (i=0; i 

_somUninit (animals [i] ) ; 

/* 

* Finally, the next line frees all 5 animals 

* with one operation. 

*/ 

SOMFree (myAnimalCluster) ; 



somRenewNolnitNoZero - Topics 
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somRenewNoZero 



somRenewNoZero - Syntax 



This method creates a new object instance using a passed block of storage. 



For backward compatibility, this method does not take an Environment parameter. 



SOMClass receiver; 

somToken memPtr; 

SOMObject rc; 

rc = somRenewNoZero (receiver, memPtr); 



somRenewNoZero Parameter - receiver 



receiver (SOMClass) 

A pointer to the class object that is to create the new instance. 



somRenewNoZero Parameter - memPtr 



memPtr (somToken) 

A pointer to the space to be used to construct a new object. 



somRenewNoZero Parameter - rc 



rc (SOMObject) 

The value of newOb/ect is returned, which is now a pointer to a valid, initialized object. 



somRenewNoZero - Parameters 



receiver (SOMClass) 

A pointer to the class object that is to create the new instance. 
memPtr (somToken) 

A pointer to the space to be used to construct a new object, 
rc (SOMObject) 

The value of newOb/ect is returned, which is now a pointer to a valid, initialized object. 



somRenewNoZero - Remarks 



The somRenew method creates a new instance of the receiving class by setting the appropriate location in the passed memory block to the 
receiving class's instance method table. Unlike somNew, these "Renew" methods use the space pointed to by memPtr rather than 
allocating new space for the object. The somRenew method automatically re-initializes the object by first zeroing the object's memory, and 
then invoking somDefaultlnit; somRenewNolnit zeros memory, but does not invoke somDefaultlnit. somRenewNolnitNoZero only sets 
the method table pointer; while somRenewNoZero calls somDefaultlnit, but does not zero memory first. 

No check is made to ensure that the passed pointer addresses enough space to hold an instance of the receiving class. The caller can 
determine the amount of space necessary by using the somGetlnstanceSize method. 

The C bindings produced by the SOM Compiler contain a macro that is a convenient shorthand for somRenew (_c/ass//ame). 



somRenewNoZero - Original Class 



SOMCIass 



somRenewNoZero - Related Methods 



Methods 



somGetlnstanceSize 

somDefaultlnit 

somNew 



somRenewNoZero - Example Code 



#include <animal.h> 

main ( ) 

{ 

void *myAnimalCluster ; 

Animal animals [5]; 

SOMCIass animalClass; 
int animalSize, i; 

animalClass = 

AnimalNewClass (Animal_Ma jorVersion, Animal_MinorVersion) ; 
animalSize = _somGetInstanceSize (animalClass) ; 

/* Round up to double-word multiple */ 
animalSize = ( (animalSize+3) /4 ) *4 ; 

/* 

* Next line allocates room for 5 objects 

* in a "cluster" with a single memory- 

* allocation operation. 

*/ 

myAnimalCluster = SOMMalloc (5*animalSize) ; 

/* 

* The for-loop that follows creates 5 initialized 

* Animal instances within the memory cluster. 

*/ 

for (i=0; i 

animals [ i ] = 

_somRenew (animalClass, myAnimalCluster+ (i*animalSize) ) ; 

/* Uninitialize the animals explicitly: */ 
for (i=0; i 




_somUninit (animals [i] ) ; 

/* 

* Finally, the next line frees all 5 animals 

* with one operation. 

*/ 

SOMFree (myAnimalCluster ) ; 



somRenewNoZero - Topics 
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somSupportsMethod 



somSupportsMethod - Syntax 



This method returns a boolean indicating whether instances of a class respond to a given (static or dynamic) method. 
For backward compatibility, this method does not take an Environment parameter. 



SOMClass receiver; 
somld methodld; 
boolean rc; 

rc = somSupportsMethod (receiver , methodld); 



somSupportsMethod Parameter - receiver 



receiver (SOMClass) 

A pointer to the class object to be tested. 



somSupportsMethod Parameter - methodld 



methodld (somld) 

An ID that represents the name of the method. 



somSupportsMethod Parameter - rc 



rc (boolean) 

Returns 1 (true) if instances of the specified class support the specified method, and 0 (false) otherwise. 



somSupportsMethod - Parameters 



receiver (SOMCIass) 

A pointer to the class object to be tested. 

methodld (somld) 

An ID that represents the name of the method, 
rc (boolean) 

Returns 1 (true) if instances of the specified class support the specified method, and 0 (false) otherwise. 



somSupportsMethod - Remarks 



The somSupportsMethod method determines if instances of the specified class respond to the specified (static or dynamic) method. 



somSupportsMethod - Original Class 



SOMCIass 



somSupportsMethod - Related Methods 



Methods 

• somRespondsTo 



somSupportsMethod - Example Code 




/* 

Note: animal supports a setSound method; 

animal does not support a doTrick method. 

*/ 

#include <animal.h> 
main ( ) 

{ 

SOMClass animalClass; 
char *methodNamel = "setSound"; 
char *methodName2 = "doTrick"; 
animalClass = 

AnimalNewClass (Animal_Ma jorVersion, Animal_MinorVersion) ; 

if (_somSupportsMethod (animalClass, 

somldFromString (methodNamel ) ) ) 
somPrintf ( "Animals respond to %s\n", methodNamel); 
if (_somSupportsMethod (animalClass, 

somldFromString (methodName2 ) ) ) 
somPrintf ( "Animals respond to %s\n", methodName2) ; 



/* 

Output from this program: 
Animals respond to setSound 
*/ 



somSupportsMethod - Topics 
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SOMCIassMgr 



File stem: somcm 
Base 

SOMObject 

Metaclass 

SOMClass 

Ancestor Classes 
SOMObject 

Description 

One instance of SOMCIassMgr is created automatically during SOM initialization. This instance (pointed to by the global variable, 
SOMCIassMgrObject ) acts as a run-time registry for all SOM class objects that exist within the current process and assists in the dynamic 
loading and unloading of class libraries. 



You can subclass SOMCIassMgr to augment the functionality of its registry. To have an instance of your subclass replace the 
SOM-supplied SOMCIassMgrObject, use the somMergelnto method to place the existing registry information from SOMCIassMgrObject 
into your new class-manager object. 

Types 

interface Repository; 

SOMCIass *SOMCIassArray; 

Attributes 

Listed below is each available attribute with its corresponding type in parentheses, followed by a description of its purpose. 

somlnterfaceRepository (Repository) 

The SOM Interface Repository object. If the Interface Repository is not available or cannot be initialized, this attribute returns 
NULL. When your program finishes using the Repository object, it should call the somDestruct method to release the reference, 
using a non-zero value for the doFree parameter. 

somRegisteredClasses (sequence<SOMCIass>) 

This is a "readonly" attribute that returns a sequence containing all of the class objects registered in the current process. When you 
have finished using the returned sequence, you should free the sequence's buffer using SOMFree. Here is a fragment of code 
written in C that illustrates the proper use of this attribute: 

sequence (SOMCIass) clsList; 

clsList = SOMCIassMgr get_somRegisteredClasses (SOMCIassMgrObject) ; 

somPrintf ("Currently registered classes : \n" ) ; 
for ( 1=0 ; i<clsList ._length; i++) 

somPrintf ("\t%s\n", SOMClass_somGetName (clsList ._buffer [i] )) ; 

SOMFree (clsList ,_buffer) ; 



New methods 

The following list shows all the SOMCIassMgr methods. 

Group: Basic Functions: 

• somLoadClassFile 

• somLocateClassFile 

• somRegisterClass 

• somUnloadClassFile 

• somUnregisterClass 

Group: Access: 

• somGetlnitFunction 

• somGetRelatedClasses 

Group: Dynamic: 

• somClassFormld 

• somFindClass 

• somFindCIsInFile 

• somMergelnto 

• somSubstituteClass 

Overridden methods 

The following list shows all the methods overridden by the SOMCIassMgr class. These methods are overridden in order to modify the 
behavior defined by an ancestor class. 

• somDumpSelflnt 

• somlnit 

• somUninit 



somClassFromld 




somClassFromld - Syntax 



This method finds a class object, given its somld, if it already exists. Does not load the class. 
For backward compatibility, this method does not take an Environment parameter. 



SOMClassMgr receiver; 
somld classld; 

SOMClass rc; 

rc = somClassFromld (receiver , classld); 



somClassFromld Parameter - receiver 



receiver (SOMClassMgr) 

Usually SOMCIassMgrObject (or a pointer to an instance of a user-supplied subclass of SOMClassMgr). 



somClassFromld Parameter - classld 



classld (somld) 

The somld of the class. This can be obtained from the name of the class using the somldFromString function. 



somClassFromld Parameter - rc 



rc (SOMClass) 

Returns a pointer to the class, or NULL if the class object does not yet exist. 



somClassFromld - Parameters 



receiver (SOMClassMgr) 

Usually SOMCIassMgrObject (or a pointer to an instance of a user-supplied subclass of SOMClassMgr). 



classld (somld) 



The somld of the class. This can be obtained from the name of the class using the somldFromString function. 



rc (SOMCIass) 

Returns a pointer to the class, or NULL if the class object does not yet exist. 



somClassFromld - Remarks 



Finds a class object, given its somld, if it already exists. Does not load the class. 

Use the somClassFromld method instead of somFindClass when you do not want the class to be automatically loaded if it does not 
already exist in the current process. 



somClassFromld - Original Class 



SOMCIassMgr 



somClassFromld - Related Methods 



Methods 



somFindClass 

somFindCIsInFile 



somClassFromld - Example Code 



#include <som.h> 

main () { 

SOMCIass myClass; 

char *myClassName = "Animal"; 

somld animalld; 

somEnvironmentNew (); 

animalld = somldFromString (myClassName) ; 

myClass = SOMClassMgr_somClassFromId (SOMClassMgrOb ject , 

animalld) ; 

if (ImyClass) 

somPrintf ("Class %s has not been loaded. \n" , myClassName); 
SOMFree (animalld) ; 

} 



This program produces the following output: 



Class Animal has not yet been loaded. 




somClassFromld - Topics 
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somFindClass 



somFindClass - Syntax 



This method finds the class object for a class. 

For backward compatibility, this method does not take an Environment parameter. 



SOMClassMgr 

somld 

long 

long 

SOMClass 



receiver; 
classld; 
ma jorVersion ; 
minorVersion ; 
rc; 



rc = _somFindClass (receiver, classld, ma jorVersion, 
minorVersion) ; 



somFindClass Parameter - receiver 



receiver (SOMClassMgr) 

Usually SOMCIassMgrObject (or a pointer to an instance of a user-supplied subclass of SOMClassMgr). 



somFindClass Parameter - classld 



classld (somld) 

The somld representing the name of the class. 



somFindClass Parameter - majorVersion 



majorVersion (long) 

The class's major version number. 



somFindClass Parameter - minorVersion 



minorVersion (long) 

The class's minor version number. 



somFindClass Parameter - rc 



rc (SOMCIass) 

A pointer to the requested class object, or NULL if the class could not be found or created. 



somFindClass - Parameters 



receiver (SOMCIassMgr) 

Usually SOMCIassMgrObject (or a pointer to an instance of a user-supplied subclass of SOMCIassMgr). 
classic! (somld) 

The somld representing the name of the class. 

majorVersion (long) 

The class's major version number. 

minorVersion (long) 

The class's minor version number. 

rc (SOMCIass) 

A pointer to the requested class object, or NULL if the class could not be found or created. 



somFindClass - Remarks 



The somFindClass method returns the class object for the specified class. This method first uses somLocateClassFile (see paragraph 
below) to obtain the name of the file where the class's code resides, then uses somFindCIsInFile. 




If the requested class has not yet been created, the somFindClass method attempts to load the class dynamically by loading its 
dynamically linked library and invoking its "new class" procedure. 

The somLocateClassFile method uses the following steps: 

1 . If the entry in the Interface Repository for the class specified by c/ass/d contains a dllname modifier, this value is used as the 
file name for loading the library. (For information about the dllname modifier, refer to the topic "Modifier statements" in Chapter 
4, "SOM IDL and the SOM Compiler,” of the SOMobjects Deve/oper Too/k/t User Gu/de .) 

2. In the absence of a dllname modifier, the class name is assumed to be the file name for the library. Use the somFindCIsInFile 
method if you wish to explicitly pass the file name as an argument. 

If ma/orVers/on and m/norVers/on are not both zero, they are used to check the class version information against the caller's expectations. 
An implementation is compatible with the specified version numbers if it has the same major version number and a minor version number 
that is equal to or greater than m/norVers/on . 



somFindClass - Original Class 



SOMCIassMgr 



somFindClass - Related Methods 



Methods 



somFindCIsInFile 

somLocateClassFile 



somFindClass - Example Code 



#include <som.h> 

/* 

* This program creates a class object 

* (from a DLL) without requiring the 

* usage binding file (.h or .xh) for 

* the class. 

*/ 

void main () 

{ 

SOMClass myClass; 
somld animalld; 

somEnvironmentNew (); 

animalld = somldFromString ("Animal"); 

/* The next statement is equivalent to: 

* #include "animal. h" 

* myClass = AnimalNewClass (0, 0) ; 

*/ 

myClass = SOMClassMgr_somFindClass (SOMClassMgrOb ject , 

animalld, 0, 0) ; 

if (myClass) 

somPrintf ("myClass: %s\n", SOMClass_somGetName (myClass)); 




else 




somFindClass - Topics 
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somFindCIsInFile 



somFindCIsInFile - Syntax 



This method finds a class object for a class. 

For backward compatibility, this method does not take an Environment parameter. 



rc = somFindCIsInFile (receiver, classld, ma jorVersion, 



minorVersion, file) ; 



somFindCIsInFile Parameter - receiver 



receiver (SOMCIassMgr) 

Usually SOMCIassMgrObject (or a pointer to an instance of a user-supplied subclass of SOMCIassMgr). 



SOMCIassMgr 



receiver; 
classld; 
ma jorVersion ; 
minorVersion ; 
file; 



somld 

long 

long 



string 

SOMClass 



rc; 



somFindCIsInFile Parameter - classld 



classic! (somld) 

The somld representing the name of the class. 



somFindCIsInFile Parameter - majorVersion 



majorVersion (long) 

The class's major version number. 



somFindCIsInFile Parameter - minorVersion 



minorVersion (long) 

The class's minor version number. 



somFindCIsInFile Parameter - file 



file (string) 

A string representing the filename to be used if dynamic loading is required. 



somFindCIsInFile Parameter - rc 



rc (SOMCIass) 

A pointer to the requested class object, or NULL if the class could not be found or created. 



somFindCIsInFile - Parameters 



receiver (SOMCIassMgr) 

Usually SOMCIassMgrObject (or a pointer to an instance of a user-supplied subclass of SOMCIassMgr). 
classld (somld) 

The somld representing the name of the class. 




majorVersion (long) 

The class's major version number. 

minorVersion (long) 

The class's minor version number. 

file (string) 

A string representing the filename to be used if dynamic loading is required, 
rc (SOMCIass) 

A pointer to the requested class object, or NULL if the class could not be found or created. 



somFindCIsInFile - Remarks 



The somFindCIsInFile method returns the class object for the specified class. This method is the same as somFindClass except that the 
caller provides the filename to be used if dynamic loading is needed. 

If the requested class has not yet been created the somFindCIsInFile method attempts to load the class dynamically by loading the 
specified library and invoking its "new class" procedure. 

If ma/orVers/on and m/norVers/on are not both zero, they are used to check the class version information against the caller's expectations. 
An implementation is compatible with the specified version numbers if it has the same major version number and a minor version number 
that is equal to or greater than m/norVers/on . 



somFindCIsInFile - Original Class 



SOMCIassMgr 



somFindCIsInFile - Related Methods 



Methods 



somFindClass 



somFindCIsInFile - Example Code 



#include <som.h> 

/* */ 

/* This program loads a class and creates */ 
/* an instance of it without requiring the */ 

/* binding (.h) file for the class. */ 

/* */ 

void main ( ) 

{ 



SOMObject my Animal; 
SOMCIass animalClass; 




char *animalName = "Animal"; 

/* 

* Filenames will be different for AIX and OS/2 

* Set animalf ile to "C : \\MYDLLS\\ ANIMAL . DLL" for OS/2. 

* Set animalfile to "/mydlls/animal . dll" for AIX. 

*/ 

char *animalFile = " /mydlls/animal . dll" ; /* AIX filename */ 

somEnvironmentNew ( ) ; 

animalClass = _somFindClsInFile (SOMClassMgrOb ject , 

somldFromString (animalName) , 

0 , 0 , 

animalFile) ; 

myAnimal = _somNew (animalClass) ; 
somPrintf ( "The class of myAnimal is %s.\.n" , 

_somGetClassName (myAnimal) ) ; 

_somFree (myAnimal) ; 

} 

/* Output from this program: */ 

/* The class of myAnimal is Animal. */ 



somFindCIsInFile - Topics 
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somGetlnitFunction 



somGetlnitFunction - Syntax 



This method obtains the name of the function that initializes the SOM classes in a class library. 
For backward compatibility, this method does not take an Environment parameter. 



SOMClassMgr receiver; 

string rc; 



rc = somGetlnitFunction (receiver ) ; 



somGetlnitFunction Parameter - receiver 



receiver (SOMCIassMgr) 

Usually SOMCIassMgrObject (or a pointer to an instance of a user-supplied subclass of SOMCIassMgr). 



somGetlnitFunction Parameter - rc 



rc (string) 

Returns a string that names the initialization function of class libraries. By default, this name is the value of the global variable 

SOMCIassInitFuncName, the default value of which is SOMInitModule. 



somGetlnitFunction - Parameters 



receiver (SOMCIassMgr) 

Usually SOMCIassMgrObject (or a pointer to an instance of a user-supplied subclass of SOMCIassMgr). 



rc (string) 

Returns a string that names the initialization function of class libraries. By default, this name is the value of the global variable 

SOMCIassInitFuncName, the default value of which is SOMInitModule. 



somGetlnitFunction - Remarks 



The somGetlnitFunction method supplies the name of the initialization function for OS/2 class libraries (DLLs) that contain more than one 
SOM class. The default implementation returns the value of the global variable SOMCIassInitFuncName, which by default is set to the 
value "SOMInitModule". 

For AIX, the name of the class initialization function is not important, since AIX class libraries should always be constructed as shared 
libraries with a designated entry point which can be executed automatically by the loader when the class is loaded. Consequently, the result 
of this method is not significant on AIX. 

Similarly, if an OS/2 class library (DLL) has been constructed with a DLL initialization function assigned by the linker, you can choose to 
invoke the <className>NewClass functions for all of the classes in the DLL during DLL initialization. In this case (as on AIX), there is no 
need to export a "SOMInitModule" function. On the other hand, if your compiler does not provide a convenient mechanism for creating a DLL 
initialization function, you can elect to export a function named "SOMInitModule" (or whatever name is ultimately returned by the 

somGetlnitFunction method). 

The OS/2 SOMCIassMgrObject, after loading a class library, will invoke the method somGetlnitFunction to obtain the name of a possible 
initialization function. If this name has been exported by the class library just loaded, the SOMCIassMgrObject calls this function to initialize 
the classes in the library. If the name has not been exported by the DLL, the SOMCIassMgrObject then looks for an exported name of the 
form <className>NewClass, where <className> is the name of the class supplied with the method that caused the DLL to be loaded. If 
the DLL exports this name, it is invoked to create the named class. 

On Windows, the SOM class manager does not call SOMInitModule. It must be called from the default Windows DLL initialization function, 
LibMain. This call is made indirectly through the SOM_ClassLibrary macro. 

Regardless of the technique employed, the SOMCIassMgrObject expects that all classes packaged in a single class library will be created 
during this sequence. 




This method is generally not invoked directly by users. User-defined subclasses of SOMCIassMgr, however, can override this method. 



somGetlnitFunction - Original Class 



SOMCIassMgr 



somGetlnitFunction - Related Methods 

Methods 

• somFindClass 

• somFindCIsInFile 

Functions 

• SOMInitModule 

Macros 

■ SOMCIassLibrary 
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somGetRelatedClasses 



somGetRelatedClasses - Syntax 



This method returns an array of class objects that were all registered during the dynamic loading of a class. 
For backward compatibility, this method does not take an Environment parameter. 



SOMCIassMgr 



receiver; 



SOMClass classObj; 

SOMClass *rc; 

rc = somGetRelatedClasses (receiver , classObj); 



somGetRelatedClasses Parameter - receiver 



receiver (SOMCIassMgr) 

Usually a pointer to SOMCIassMgrObject, or a pointer to an instance of a user-defined subclass of SOMCIassMgr. 



somGetRelatedClasses Parameter - classObj 



classObj (SOMClass) 

A pointer to a SOMClass object. 



somGetRelatedClasses Parameter - rc 



rc (SOMClass *) 

Returns a pointer to an array of pointers to class objects, or NULL, if the specified class was not dynamically loaded. 



somGetRelatedClasses - Parameters 



receiver (SOMCIassMgr) 

Usually a pointer to SOMCIassMgrObject, or a pointer to an instance of a user-defined subclass of SOMCIassMgr. 

classObj (SOMClass) 

A pointer to a SOMClass object. 

rc (SOMClass *) 

Returns a pointer to an array of pointers to class objects, or NULL, if the specified class was not dynamically loaded. 



somGetRelatedClasses - Remarks 



The somGetRelatedClasses method returns an array of class objects that were all registered during the dynamic loading of the specified 
class. These classes are considered to define an affinity group. Any class is a member of at most one affinity group. The affinity group 
returned by this call is the one containing the class identified by the c/assObj parameter. 



The first element in the array is either the class that caused the group to be loaded, or the special value -1 , which means that the class 
manager is currently in the process of unregistering and deleting the affinity group (only class-manager objects would ever see this value). 
The remainder of the array consists of pointers to class objects, ordered in reverse chronological sequence to that in which they were 
originally registered. This list includes the given argument, c/assObj , as one of its elements, as well as the class that caused the group to be 
loaded (also given by the first element of the array). The array is terminated by a NULL pointer as the last element. 

Use SOMFree to release the array when it is no longer needed. If the supplied class was not dynamically loaded, it is not a member of any 
affinity group and NULL is returned. 



somGetRelatedClasses - Original Class 



SOMCIassMgr 



somGetRelatedClasses - Related Methods 



Methods 



somGetlnitFunction 



somGetRelatedClasses - Example Code 



#include <som.h> 

SOMClass myClass, *relatedClasses ; 
string className; 
long i; 

className = SOMClass_somGetName (myClass) ) ; 
relatedClasses = SOMClassMgr_somGetRelatedClasses 

(SOMClassMgrOb ject, myClass) ; 
if (relatedClasses && *relatedClasses) { 

somPrintf ("Class=%s, related classes are: ", className); 
for (i=l; relatedClasses [i] ; i++) 

somPrintf ("%s " , SOMClass_somGetName (relatedClasses [ i ])) ; 
somPrintf ("\n"); 

somPrintf ("Class that caused loading was %s\n" , 
relatedClasses [ 0 ] == (SOMClass) -1 ? "-1" : 
SOMClass_somGetName (relatedClasses [0] ) ) ; 

SOMFree (relatedClasses) ; 

} else 

somPrintf ("No classes related to %s\n", className); 



somGetRelatedClasses - Topics 
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somLoadClassFile 



somLoadClassFile - Syntax 



This method dynamically loads a class. 

For backward compatibility, this method does not take an Environment parameter. 



SOMClassMgr 

somID 

long 

long 

string 

SOMClass 



receiver; 

classld; 

ma jorVersion ; 

minorVersion ; 

file; 

rc; 



rc = somLoadClassFile (receiver, classld, ma jorVersion, 
minorVersion, file) ; 



somLoadClassFile Parameter - receiver 



receiver (SOMClassMgr) 

Usually SOMCIassMgrObject (or a pointer to an instance of a user-supplied subclass of SOMClassMgr). 



somLoadClassFile Parameter - classld 



classld (somID) 

The somld representing the name of the class to load. 



somLoadClassFile Parameter - majorVersion 



majorVersion (long) 

The major version number used to check the compatibility of the class's implementation with the caller's expectations. 



somLoadClassFile Parameter - minorVersion 



minorVersion (long) 

The minor version number used to check the compatibility of the class's implementation with the caller's expectations. 



somLoadClassFile Parameter - file 



file (string) 

The name of the dynamically linked library file containing the class. The name can be either a simple, unqualified name (without any 
extension) or a fully qualified (or path) file name, as appropriate for your operating system. For example, on OS/2, fi/e could be 
c:\myhome\myapp\basename.dll or else basename (but not basename.dll). 



somLoadClassFile Parameter - rc 



rc (SOMCIass) 

Returns a pointer to the class object, or NULL if the class could not be loaded or the class object could not be created. 



somLoadClassFile - Parameters 



receiver (SOMCIassMgr) 

Usually SOMCIassMgrObject (or a pointer to an instance of a user-supplied subclass of SOMCIassMgr). 
classld (somID) 

The somld representing the name of the class to load. 

majorVersion (long) 

The major version number used to check the compatibility of the class's implementation with the caller's expectations. 

minorVersion (long) 

The minor version number used to check the compatibility of the class's implementation with the caller's expectations, 
file (string) 

The name of the dynamically linked library file containing the class. The name can be either a simple, unqualified name (without any 
extension) or a fully qualified (or path) file name, as appropriate for your operating system. For example, on OS/2, fi/e could be 
c:\myhome\myapp\basename.dll or else basename (but not basename.dll). 

rc (SOMCIass) 

Returns a pointer to the class object, or NULL if the class could not be loaded or the class object could not be created. 




somLoadClassFile - Remarks 



The SOMCIassMgr object uses the somLoadClassFile method to load a class dynamically during the execution of somFindClass or 
somFindCIsInFile. A SOM class object representing the class is expected to be created and registered as a result of this method. 

The somLoadClassFile method can be overridden to load or create classes dynamically using your own mechanisms. If you simply wish to 
change the name of the procedure that is called to initialize the classes in a library, override somGetlnitFunction instead. 

This method is provided to permit user-created subclasses of SOMCIassMgr to handle the loading of classes by overriding this method. Do 
not invoke this method directly; instead, use somFindClass or somFindCIsInFile. 



somLoadClassFile ■ 


■ Original Class 


SOMCIassMgr 





somLoadClassFile ■ 


■ Related Methods 


Methods 

• somFindClass 

• somFindCIsInFile 

• somGetlnitFunction 

• somUnloadClassFile 





somLoadClassFile ■ 
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somLocateClassFile 



somLocateClassFile - Syntax 



This method determines the file that holds a class to be dynamically loaded. 

For backward compatibility, this method does not take an Environment parameter. 



SOMClassMgr 

somld 

long 

long 

string 



receiver; 
classld; 
ma jorVersion ; 
minorVersion ; 
rc; 



rc = somLocateClassFile (receiver, classld, 
ma jorVersion, minorVersion) ; 



somLocateClassFile Parameter - receiver 



receiver (SOMClassMgr) 

Usually SOMCIassMgrObject (or a pointer to an instance of a user-supplied subclass of SOMClassMgr). 



somLocateClassFile Parameter - classic! 



classld (somld) 

The somld representing the name of the class to locate. 



somLocateClassFile Parameter - majorVersion 



majorVersion (long) 

The major version number used to check the compatibility of the class's implementation with the caller's expectations. 



somLocateClassFile Parameter - minorVersion 



minorVersion (long) 

The minor version number used to check the compatibility of the class's implementation with the caller's expectations. 



somLocateClassFile Parameter - rc 



rc (string) 

Returns the name of the file containing the class. 



somLocateClassFile - Parameters 



receiver (SOMCIassMgr) 

Usually SOMCIassMgrObject (or a pointer to an instance of a user-supplied subclass of SOMCIassMgr). 
classld (somld) 

The somld representing the name of the class to locate. 

majorVersion (long) 

The major version number used to check the compatibility of the class's implementation with the caller's expectations. 

minorVersion (long) 

The minor version number used to check the compatibility of the class's implementation with the caller's expectations, 
rc (string) 

Returns the name of the file containing the class. 



somLocateClassFile - Remarks 



The SOMCIassMgr object uses the somLocateClassFile method when executing somFindclass to obtain the name of a file to use when 
dynamically loading a class. The default implementation consults the Interface Repository for the value of the d//name modifier of the class; 
if no d//name modifier was specified, the method simply returns the class name as the expected filename. 

If you override the somLocateClassFile method in a user-supplied subclass of SOMCIassMgr, the name you return can be either a simple, 
unqualified name without any extension or a fully-qualified file name. Generally speaking, you would not invoke this method directly. It is 
provided to permit customization of subclasses of SOMCIassMgr through overriding. 



somLocateClassFile - Original Class 

SOMCIassMgr 



somLocateClassFile - Related Methods 



Methods 



• somFindClass 

• somFindCIsInFile 

• somGetlnitFunction 

• somLoadClassFile 

• somUnloadClassFile 
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som Merge Into 



somMergelnto - Syntax 



This method transfers SOM class registry information to another SOMCIassMgr instance. 
Note: For backward compatibility, this method does not take an Environment parameter. 

SOMCIassMgr receiver; 

SOMCIassMgr target; 

somMergelnto (receiver, target); 



somMergelnto Parameter - receiver 



receiver (SOMCIassMgr) 

Usually SOMCIassMgrObject (or a pointer to an instance of a user-supplied subclass of SOMCIassMgr). 



somMergelnto Parameter - target 



target (SOMCIassMgr) 

A pointer to another instance of SOMCIassMgr or one of its subclasses. 



som Merge Into Parameter - rc 



somMergelnto - Parameters 



receiver (SOMCIassMgr) 

Usually SOMCIassMgrObject (or a pointer to an instance of a user-supplied subclass of SOMCIassMgr). 
target (SOMCIassMgr) 

A pointer to another instance of SOMCIassMgr or one of its subclasses. 



rc 



somMergelnto - Remarks 



The somMergelnto method transfers the SOMCIassMgr registry information from one object to another. The target object is required to be 
an instance of SOMCIassMgr or one of its subclasses. At the completion of this operation, the target object can function as a replacement 
for the receiver. The receiver object (which is then in a newly uninitialized state) is placed in a mode where all methods invoked on it will be 
delegated to the target object. If the receiving object is the instance pointed to by the global variable SOMCIassMgrObject, then 
SOMCIassMgrObject is reassigned to point to the target object. 

Subclasses of SOMCIassMgr that override the somMergelnto method should transfer their section of the class manager object from the 
target to the receiver, then invoke their parent's somMergelnto method as the final step. 

Invoke this method only if you are creating your own subclass of SOMCIassMgr. You can invoke somMergelnto from an initializer for your 
new class manager. 



somMergelnto - Original Class 

SOMCIassMgr 



somMergelnto - Example Code 



// === IDL For the New Class Manager === 
#include <somcm.idl> 



interface NewCM : SOMCIassMgr { 

implementation { 




somDef aultlnit : override; 



} ; 

} ; 

// === C++ implementation for NewCM === 



#define SOM_Module_merge_Source 
#include "merge. xih" 

SOM_Scope void SOMLINK somDef aultlnit (NewCM *somSelf , 



NewCMData *somThis; /* set in Beginlnitializer */ 
somlnitCtrl globalCtrl; 
somBooleanVector myMask; 

NewCMMethodDebug ("NewCM", " somDef ault Init " ) ; 
NewCM_Begin Ini tializer_somDef aultlnit ; 



Ctrl) 



NewC_Init_SOMClassMgr_somDef aultlnit (somSelf , Ctrl) ; 

/* 

* local NewCM initialization code added by programmer 
*/ 



SOMClassMgrOb ject->somMerge!nto (somSelf ) ; 



// === C++ test program === 

#include emerge. xh> 
main ( ) 

{ 

NewCM *ncm = new NewCM; 
SOMClassMgrOb ject->somDumpSelf (0) ; 



// === Output from test program === 



{An instance of class NewCM at address 20084388 
1 classIdSpaceSize : 3200 

1 classIdHashTableSize : 397 

1 loadAf f inity : 0 

1 nextLoadAff inity : 1 

1 IR Class: 00000000, IR Object: 00000000 



1 




-Class-- 


- -Token — 


- Aff 


Seq Id 


- Name 


1 [ 


0] 


20077A48 


00000000 


000 


001 


2008260C 


SOMObject 


1 [ 


1] 


2007FB38 


00000000 


000 


000 


200825EC 


SOMClassMgr 


1 [ 


2] 


20083B08 


00000000 


000 


004 


2008436C 


NewCM 


1 [ 


3] 


20077BD8 


00000000 


000 


002 


2008262C 


SOMClass 


1 [ 


4] 


20082668 


00000000 


000 


003 


2008315C 





SOMParentDerivedMetaclass 
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somRegisterClass 



somRegisterClass - Syntax 



This method adds a class object to the SOM run-time class registry. 



Note: For backward compatibility, this method does not take an Environment parameter. 



SOMClassMgr receiver; 

SOMClass classObj; 

somRegisterClass (receiver, classObj) ; 



somRegisterClass Parameter - receiver 



receiver (SOMClassMgr) 

Usually SOMCIassMgrObject (or a pointer to an instance of a user-supplied subclass of SOMClassMgr) 



somRegisterClass Parameter - classObj 



classObj (SOMClass) 

A pointer to the class object to add to the SOM class registry. 



somRegisterClass Parameter - rc 



rc 



somRegisterClass - Parameters 



receiver (SOMClassMgr) 

Usually SOMCIassMgrObject (or a pointer to an instance of a user-supplied subclass of SOMClassMgr) 



classObj (SOMCIass) 

A pointer to the class object to add to the SOM class registry. 

rc 

somRegisterClass - Remarks 

The somRegisterClass method adds a class object to the SOM run-time class registry maintained by SOMCIassMgrObject. 

All SOM run-time class objects should be registered with the SOMCIassMgrObject. This is done automatically during the execution of the 
somClassReady method as class objects are created. 



somRegisterClass ■ 


■ Original Class 


SOMCIassMgr 





somRegisterClass ■ 


■ Related Methods 


Methods: 

• somUnregisterClass 
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somSubstituteClass 



somSubstituteClass - Syntax 



This method causes the somFindClass, somFindCIsInFile, and somClassFromld methods to substitute one class for another. 



Note: For backward compatibility, this method does not take an Environment parameter. 



SOMClassMgr 

string 

string 

long 



receiver; 
origClassName; 
newClassName ; 
rc; 



rc = somSubstituteClass (receiver, origClassName, 
newClassName) ; 



somSubstituteClass Parameter - receiver 



receiver (SOMClassMgr) 

Usually SOMCIassMgrObject or a pointer to an instance of a user-defined subclass of SOMClassMgr. 



somSubstituteClass Parameter - origClassName 



origClassName (string) 

A NULL terminated string containing the old class name. 



somSubstituteClass Parameter - newClassName 



newClassName (string) 

A NULL terminated string containing the new class name. 



somSubstituteClass Parameter - rc 



rc (long) 

The somSubstituteClass method returns a value of zero to indicate success; a non-zero value indicates an error was detected. 



somSubstituteClass - Parameters 



receiver (SOMCIassMgr) 

Usually SOMCIassMgrObject or a pointer to an instance of a user-defined subclass of SOMCIassMgr. 
origClassName (string) 

A NULL terminated string containing the old class name. 

newClassName (string) 

A NULL terminated string containing the new class name, 
rc (long) 

The somSubstituteClass method returns a value of zero to indicate success; a non-zero value indicates an error was detected. 



somSubstituteClass - Remarks 



The somSubstituteClass method causes the somFindClass, somFindCIsInFile, and somClassFromld methods to return the class 
named newC/ass/Vame whenever they would normally return the class named origC/assName . This effectively results in class 
newC/assName replacing or substituting for class origC/ass/Vame . For example, the <origClassName>New macro will subsequently 
create instances of newC/assName . 

Some restrictions are enforced to ensure that this works well. Both class origC/ass/Vame and class newC/assName must have been 
already registered before issuing this method, and newC/ass must be an immediate child of origC/ass. In addition (although not enforced), 
no instances should exist of either class at the time this method is invoked. 

A convenience macro (SOM_SubstituteClass) is provided for C or C++ users. In one operation, it creates both the old and the new class 
and then substitutes the new one in place of the old. The use of both the somSubstituteClass method and the SOM_SubstituteClass 
macro is illustrated in the example below. 



somSubstituteClass - Original Class 



SOMCIassMgr 



somSubstituteClass - Related Methods 



Methods: 

• somClassFromld 

• somFindClass 

• somFindCIsInFile 

• somMergelnto 



somSubstituteClass - Example Code 



♦include <student.h> 




#include <mystud.h> 

/* Macro form */ 

SOM_SubstituteClass (Student, MyStudent) ; 

/* Direct use of the method, equivalent to 
* the macro form above. 

*/ 

{ 

SOMClass origClass, replacementClass; 

origClass = StudentNewClass (Student_Ma jorVersion, 

Student_MinorVersion) ; 

replacementClass = MyStudentNewClass (MyStudent_Ma jorVersion, 

MyStudent_MinorVersion) ; 

SOMClassMgr_somSubstituteClass ( 

SOMClass_somGetName (origClass) , 

SOMClass_somGetName (replacementClass) ) ; 

} 
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somUnloadClassFile 



somUnloadClassFile - Syntax 



This method unloads a dynamically loaded class and frees the class's object. 



Note: For backward compatibility, this method does not take an Environment parameter. 



SOMClassMgr receiver; 

SOMClass class; 

long rc; 

rc = somUnloadClassFile (receiver , class); 



somUnloadClassFile Parameter - receiver 



receiver (SOMCIassMgr) 

Usually SOMCIassMgrObject (or a pointer to an instance of a user-supplied subclass of SOMCIassMgr). 



somUnloadClassFile Parameter - class 



class (SOMCIass) 

A pointer to the class to be unloaded. 



somUnloadClassFile Parameter - rc 



rc (long) 

The somUnloadClassFile method returns 0 if the class was successfully unloaded; otherwise, it returns a system-specific non-zero 
error code from either the OS/2 DosFreeModule or the AIX unload system call. 



somUnloadClassFile - Parameters 



receiver (SOMCIassMgr) 

Usually SOMCIassMgrObject (or a pointer to an instance of a user-supplied subclass of SOMCIassMgr). 
class (SOMCIass) 

A pointer to the class to be unloaded, 
rc (long) 

The somUnloadClassFile method returns 0 if the class was successfully unloaded; otherwise, it returns a system-specific non-zero 
error code from either the OS/2 DosFreeModule or the AIX unload system call. 



somUnloadClassFile - Remarks 



The somUnregisterClass method uses the somUnloadClassFile method to unload a dynamically loaded class. This releases the class's 
code and unregisters all classes in the same affinity group. (Use somGetFtelatedClasses to find out which other classes are in the same 
affinity group.) 

The class object is freed whether or not the class' s shared library could be unloaded. If the class was not registered, an error condition is 
raised and SOMError is invoked. This method is provided to permit user-created subclasses of SOMCIassMgr to handle the unloading of 
classes by overriding this method. Do not invoke this method directly; instead, invoke somUnregisterClass. 



somUnloadClassFile - Original Class 




SOMCIassMgr 



somUnloadClassFile - Related Methods 



Methods: 



somLoadClassFile 

somRegisterClass 

somUnregisterClass 

somGetRelatedClasses 
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somUnregisterClass 



somUnregisterClass - Syntax 



This method removes a class object from the SOM run-time class registry. 



Note: For backward compatibility, this method does not take an Environment parameter. 



SOMCIassMgr receiver; 

SOMClass class; 

long rc; 

rc = somUnregisterClass (receiver, class) ; 



somUnregisterClass Parameter - receiver 



receiver (SOMCIassMgr) 

Usually SOMCIassMgrObject (or a pointer to an instance of a user-supplied subclass of SOMCIassMgr). 



somUnregisterClass Parameter - class 



class (SOMCIass) 

A pointer to the class to be unregistered. 



somUnregisterClass Parameter - rc 



rc (long) 

The somUnregisterClass method returns 0 for a successful completion, or non-zero to denote failure. 



somUnregisterClass - Parameters 



receiver (SOMCIassMgr) 

Usually SOMCIassMgrObject (or a pointer to an instance of a user-supplied subclass of SOMCIassMgr). 
class (SOMCIass) 

A pointer to the class to be unregistered, 
rc (long) 

The somUnregisterClass method returns 0 for a successful completion, or non-zero to denote failure. 



somUnregisterClass - Remarks 



The somUnregisterClass method unregisters a SOM class and frees the class object. If the class was dynamically loaded, it is also 
unloaded using somUnloadClassFile (which causes its entire affinity group to be unloaded as well). 



somUnregisterClass - Original Class 



SOMCIassMgr 




somUnregisterClass - Related Methods 



Methods: 



somLoadClassFile 

somRegisterClass 

somUnloadClassFile 



somUnregisterClass - Example Code 



#include <som.h> 

void main () 

{ 

long rc; /* Return code */ 

SOMClass animalClass; 

/* The next 2 lines declare a static form of somld */ 
string animalClassName = "Animal"; 
somld animalld = &animalClassName; 

somEnvironmentNew () ; 

animalClass = SOMClassMgr_somFindClass (SOMClassMgrOb ject , 

animalld, 0, 0) ; 

if (! animalClass ) { 

somPrintf ("Could not load class. \n" ); 
return ; 

} 

rc = SOMClassMgr_somUnregisterClass (SOMClassMgrOb ject , 

animalClass) ; 

if (rc) 

somPrintf ("Could not unregister class, error code: %ld.\n 

rc 

else 

somPrintf ("Class successfully unloaded . \n" ) ; 

} 
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SOMObject 



File stem: somobj 



Base 

None. 

Metaclass 

SOMCIass 

Ancestor Classes 
None 

Description 

SOMObject is the root class for all SOM classes. That is, all SOM classes must be subclasses of SOMObject or of some other class 
derived from SOMObject. SOMObject introduces no instance data, so objects whose classes inherit from SOMObject incur no size 
increase. They do inherit a suite of methods that provide the behavior required of all SOM objects. Three of these methods are typically 
overridden by any subclass that has instance data- somDefaultlnit, somDestruct, and somDumpSelflnt. See the descriptions of these 
methods for further information. 

New methods 

The following list shows all the SOMObject methods. 

Group: Initialization/Termination: 

• somFree 

• somDefaultlnit 

• somDestruct 

• somlnit 

• somUninit 

• somDefaultAssign 

• somDefaultConstAssign 

• somDefaultConstCopylnit 

• somDefaultCopylnit 

Group: Access: 

• somGetClass 

• somGetClassName 

• somGetSize 

Group: Testing: 

• somlsA 

• somlsInstanceOf 

• somRespondsTo 

Group: Dynamic: 

• somDispatchA 

• somDispatchD 

• somDispatchL 

• somDispatchV 

• somDispatch 

• somClassDispatch 

• somCastObj 

• somResetObj 

Group: Developer Support: 

• somDumpSelf 

• somDumpSelflnt 

• somPrintSelf 

Overridden methods 

There are currently no overridden methods defined for the SOMObject class. 




somCastObj 



somCastObj - Syntax 



This method changes the behavior of an object to that defined by any ancestor of the true class of the object. 



SOMObject receiver; 

SOMClass ancestor; 

boolean rc; 

rc = somCastObj (receiver, ancestor) ; 



somCastObj Parameter - receiver 

receiver (SOMObject) 

A pointer to an object of type SOMObject. 



somCastObj Parameter - ancestor 



ancestor (SOMClass) 

A pointer to a class that is an ancestor of the actual class of the receiver. 



somCastObj Parameter - rc 



rc (boolean) 



TRUE Returns 1 (TRUE) if the operation is successful. 

FALSE Returns 0 (false) if the operation is not successful. The operation fails if ancestor is not actually an 

ancestor of the class of the object. 



somCastObj - Parameters 



receiver (SOMObject) 

A pointer to an object of type SOMObject. 

ancestor (SOMCIass) 

A pointer to a class that is an ancestor of the actual class of the receiver, 
rc (boolean) 



TRUE Returns 1 (TRUE) if the operation is successful. 

FALSE Returns 0 (false) if the operation is not successful. The operation fails if ancestor is not actually an 

ancestor of the class of the object. 



somCastObj - Remarks 



This method changes the behavior of an object so that its behavior will be that of an instance of the indicated ancestor class (with respect to 
any method supported by the ancestor). The behavior of the object on methods not supported by the ancestor remains unchanged. 

This operation actually changes the class of the object (since an object's behavior is defined by its class). The name of the new class is 
derived from the initial name of the object's class and the name of the ancestor class, as illustrated in the Example. 

This method may be used on an object multiple times, always with the restriction that the ancestor class whose behavior is selected is 
actually an ancestor of the true (original) class of the object. 



somCastObj - Original Class 



SOMObject 



somCastObj - Related Methods 



Methods 

• somResetObj 



somCastObj - Example Code 



#include <som.h> 
main ( ) 

{ 

SOMClassMgr cm = somEnvironmentNew ( ) ; 
SOM_Test (1 == _somCastObj (cm, _SOMObject) ) ; 
_somDumpSelf (cm, 0) ) ; 

SOM_Test (1 == _somResetObj (cm) ) ; 
_somDumpSelf (cm, 0) ; 




/* output: 

* {An instance of class SOMClassMgr->SOMOb ject 

* at address 20061268 

* } 

* {An instance of class SOMClassMgr at address 20061268 

* ... <SOMClassMgr State Information> . . . 

* } 

*/ 



somCastObj - Topics 
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somDefaultAssign 



somDefaultAssign - Syntax 



This method provides support for an object-assignment operator. May be overridden, but, if appropriate, somDefaultConstAssign should 
be overridden instead. 



SOMObject 

somlnitCtrl 

SOMObject 



receiver; 
Ctrl; 
f romOb j ; 



somDefaultAssign (receiver, Ctrl, fromObj) ; 



somDefaultAssign Parameter - receiver 



receiver (SOMObject) 

A pointer to an object of an arbitrary SOM class, S. 



somDefaultAssign Parameter - Ctrl 



Ctrl (somlnitCtrl) 

A pointer to a somlnitCtrl structure, or NULL. 



somDefaultAssign Parameter - fromObj 



fromObj (SOMObject) 

A pointer to an object of class S or some class descended from S. 



somDefaultAssign Parameter - rc 



rc 



somDefaultAssign - Parameters 



receiver (SOMObject) 

A pointer to an object of an arbitrary SOM class, S. 

Ctrl (somlnitCtrl) 

A pointer to a somlnitCtrl structure, or NULL. 
fromObj (SOMObject) 

A pointer to an object of class S or some class descended from S. 



rc 



somDefaultAssign - Remarks 



In C++, assignment to an object of class "X" is accomplished by using (an appropriate overloading of) the assignment operator provided by 
"X". To make assignment available on all SOM objects, SOMObject provides the somDefaultAssign and somDefaultConstAssign 
methods. The default behavior of these methods is that they do a shallow copy of data from one object to another. Users should generally 
use the somDefaultAssign method for doing object assignment. 

When a shallow copy is not appropriate for the data introduced by a class, and it is possible to perform the copy without modifying fromObj , 
it is recommended that the class implementor override the somDefaultConstAssign method for that class. 




The considerations important to overriding somDefaultAssign are similar to those described in the SOMobjects Users Guide for overriding 
somDefaultlnit. (See "Initializing and Uninitializing Objects" in Chapter 5, "Implementing Classes in SOM.") The basic difference between 
somDefaultlnit and somDefaultAssign is that the latter method takes an object ( fromObj ) as a source argument for assignment of values 
to the receiver. 



somDefaultAssign - Original Class 

SOMObject 



somDefaultAssign - Related Methods 



Methods 



somDefaultlnit 

somDefaultConstAssign 

somDefaultCopylnit 

somDefaultConstCopylnit 



somDefaultAssign - Example Code 



// C++ SOMObjects Toolkit Code 
#include <Y.xh> 

main ( ) 

{ 

X *x = new X; 

Y *y = new Y; // assume Y is derived from X 

x->somDef aultAssign ( 0 , y ) 

// the x object has now been assigned values from y 



somDefaultAssign - Topics 
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somDefaultConstAssign 



somDefaultConstAssign - Syntax 



Provides support for a "const" object-assignment operator. Designed to be overridden. 



SOMObject receiver; 

somlnitCtrl Ctrl; 

SOMObject fromObj; 

somDefaultConstAssign (receiver , Ctrl, fromObj); 



somDefaultConstAssign Parameter - receiver 



receiver (SOMObject) 

A pointer to an object of an arbitrary SOM class, S. 



somDefaultConstAssign Parameter - Ctrl 



Ctrl (somlnitCtrl) 

A pointer to a somlnitCtrl structure, or NULL. 



somDefaultConstAssign Parameter - fromObj 



fromObj (SOMObject) 

A pointer to an object of class S or some class descended from S. 



somDefaultConstAssign Parameter - rc 



rc 



somDefaultConstAssign - Parameters 



receiver (SOMObject) 

A pointer to an object of an arbitrary SOM class, S. 

Ctrl (somlnitCtrl) 

A pointer to a somlnitCtrl structure, or NULL. 
fromObj (SOMObject) 

A pointer to an object of class S or some class descended from S. 



rc 



somDefaultConstAssign - Remarks 



In C++, assignment to an object of class "X" is accomplished by using (an appropriate overloading of) the assignment operator provided by 
"X". To make assignment available on all SOM objects, SOMObject introduces the somDefaultAssign and somDefaultConstAssign 
methods. The default behavior of these methods is to perform a shallow copy of data from one object to another. When this default is not 
appropriate for a class, and it is possible to perform the copy without modifying fromObj , it is recommended that the class implementor 
override the somDefaultConstAssign method. 

Generally, an object user should use the somDefaultAssign method to perform object assignment. 

The considerations important to overriding somDefaultConstAssign are similar to those described in the SOMobjects Users Guide for 
overriding somDefaultlnit. (See "Initializing and Uninitializing Objects" in Chapter 5, "Implementing Classes in SOM.”) The basic difference 
between somDefaultlnit and somDefaultConstAssign is that the latter method takes an object ( fromObj ) as an argument that is to be 
copied. 



somDefaultConstAssign - Original Class 

SOMObject 



somDefaultConstAssign - Related Methods 



Methods 



somDefaultlnit 

somDefaultAssign 

somDefaultCopylnit 

somDefaultConstCopylnit 



somDefaultConstAssign - Example Code 




// IDL for a class that overrides somDef aultConstAssign 
#include <X.idl> 



interface Y : X { 

implementation { 

somDef aultConstAssign : override, 



init ; 
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somDefaultConstCopylnit 



somDefaultConstCopylnit - Syntax 



This method provides support for passing objects as call-by-value object parameters in methods introduced by DTS C++ classes. Designed 
to be overridden. 



SOMObject receiver; 

somlnitCtrl Ctrl; 

SOMObject fromObj; 

somDef aultConstCopyinit (receiver , Ctrl, fromObj); 



somDefaultConstCopylnit Parameter - receiver 



receiver (SOMObject) 

A pointer to an uninitialized object of an arbitrary SOM class, S. 



somDefaultConstCopylnit Parameter - Ctrl 



Ctrl (somlnitCtrl) 

A pointer to a somlnitCtrl structure, or NULL. 



somDefaultConstCopylnit Parameter - fromObj 



fromObj (SOMObject) 

A pointer to an object of class S or some class descended from S. 



somDefaultConstCopylnit Parameter - rc 



rc 



somDefaultConstCopylnit - Parameters 



receiver (SOMObject) 

A pointer to an uninitialized object of an arbitrary SOM class, S. 
Ctrl (somlnitCtrl) 

A pointer to a somlnitCtrl structure, or NULL. 
fromObj (SOMObject) 

A pointer to an object of class S or some class descended from S. 



rc 



somDefaultConstCopylnit - Remarks 



The somDefaultConstCopylnit method would be called a "copy constructor" in C++. In SOM, this concept is supported using an object 
initializer that accepts the object to be copied as an argument. Copy constructors are used in C++ to pass objects by value. They initialize 
one object by making it be a copy of another object. In SOM, objects are always passed by reference, so arguments to DTS C++ methods 
that receive call-by-value object parameters are actually passed by reference. But, to correctly support the semantics of DTS C++ 
call-by-value arguments, it is necessary to actually pass a copy of the intended argument. A copy constructor can be used to make this 
copy. 




The default behavior provided by somDefaultConstCopylnit is to do a shallow copy of each ancestor class's introduced instance variables. 
The object being copied is not changed. When a shallow copy is not appropriate, and it is possible to avoid changing fromObj , a class 
implementor should override somDefaultConstCopylnit (for example, to do a deep copy for certain variables), but should respect the 
constraint of not modifying the object being copied. 

In general, object users should use somDefaultCopylnit to copy an object. 

The considerations important to overriding somDefaultConstCopylnit are similar to those described in the SOMobjects Users Gu/de for 
overriding somDefaultlnit. (See "Initializing and Uninitializing Objects" in Chapter 5, "Implementing Classes in SOM.") The basic difference 
between somDefaultlnit and somDefaultConstCopylnit is that the latter method takes an object ( fromObj ) as an argument that is to be 
copied. 



somDefaultConstCopylnit - Original Class 

SOMObject 



somDefaultConstCopylnit - Related Methods 



Methods 

• somDefaultlnit 

• somDefaultCopylnit 

• somDefaultAssign 

• somDefaultConstAssign 



somDefaultConstCopylnit - Example Code 



// IDL for a class that overrides somDefaultConstCopylnit 
interface X : SOMObject 
{ 



implementation { 

somDefaultConstCopylnit : override, 



init ; 
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somDefaultCopylnit 



somDefaultCopylnit - Syntax 



This method provides support for call-by-value object parameters in methods introduced by DTS C++ classes. May be overridden, but, if 
appropriate, somDefaultConstCopylnit should be overridden instead. 



SOMObject receiver; 

somlnitCtrl Ctrl; 

SOMObject fromObj; 

somDefaultCopylnit (receiver , Ctrl, fromObj); 



somDefaultCopylnit Parameter - receiver 



receiver (SOMObject) 

A pointer to an uninitialized object of an arbitrary SOM class, S. 



somDefaultCopylnit Parameter - Ctrl 



Ctrl (somlnitCtrl) 

A pointer to a somlnitCtrl structure, or NULL. 



somDefaultCopylnit Parameter - fromObj 



fromObj (SOMObject) 

A pointer to an object of class S or some class descended from S. 



somDefaultCopylnit Parameter - rc 



rc 



somDefaultCopylnit - Parameters 



receiver (SOMObject) 

A pointer to an uninitialized object of an arbitrary SOM class, S. 
Ctrl (somlnitCtrl) 

A pointer to a somlnitCtrl structure, or NULL. 
fromObj (SOMObject) 

A pointer to an object of class S or some class descended from S. 



rc 



somDefaultCopylnit - Remarks 



The somDefaultCopylnit method would be called a "copy constructor" in C++. In SOM, this concept is supported using an object initializer 
that accepts the object to be copied as an argument. Copy constructors are used in C++ to pass objects by value. They initialize one object 
by making it be a copy of another object. In SOM, objects are always passed by reference, so arguments to DTS C++ methods that receive 
call-by-value object parameters are actually passed by reference. But, to correctly support the semantics of DTS C++ call-by-value 
arguments, it is necessary to actually pass a copy of the intended argument. In general, somDefaultCopylnit should be used to make this 
copy. 

The default behavior provided by somDefaultCopylnit is to do a shallow copy of each ancestor class's introduced instance variables. 
However, a class may always override this default behavior (for example, to do a deep copy for certain variables). If it is possible to avoid 
modification of fromObj when doing the copy, the method somDefaultConstCopylnit should be overridden for this purpose. Only if this is 
not possible (and shallow copy is not appropriate) would it be appropriate to override somDefaultCopylnit. 

The considerations important to overriding somDefaultCopylnit are similar to those described in the SOMobjects Users Gu/de for 
overriding somDefaultlnit. (See "Initializing and Uninitializing Objects" in Chapter 5, "Implementing Classes in SOM.") The basic difference 
between somDefaultlnit and somDefaultCopylnit is that the latter method takes an object ( fromObj ) as an argument that is to be copied. 



somDefaultCopylnit - Original Class 

SOMObject 



somDefaultCopylnit - Related Methods 



Methods 



somDefaultlnit 

somDefaultConstCopylnit 




somDefaultAssign 

somDefaultConstAssign 



somDefaultCopylnit - Example Code 



// IDL produced by a DTS C++ compiler for a DTS C++ class 
interface X : SOMObject 
{ 



void foo(in SOMClass 
implementation { 

foo: cxxdecl 



arg) ; 

= "void foo (SOMClass 



arg) " ; 



// 



call-by-value 



// C++ SOMObjects Toolkit Code 
#include <X.xh> 

#include <somcls.xh> 
main ( ) 

{ 

X *x = new X; 

SOMClass *arg = _SOMClass->somNewNoInit ( ) ; 

// make arg be a copy of the X class object 

arg->somDefaultCopyInit (0,_X) ; 

x->foo (arg) ; // call foo with the copy 



somDefaultCopylnit - Topics 



Select an item: 
Syntax 
Parameters 
Returns 
Remarks 
Original Class 
Example Code 
Related Methods 
Glossary 



somDefaultlnit 



somDefaultlnit - Syntax 



This method initializes instance variables and attributes in a newly created object. Replaces somlnit as the preferred method for default 
object initialization. For performance reasons, it is recommended that somDefaultlnit always be overridden by classes. 



SOMObject receiver; 

somlnitCtrl Ctrl; 

somDef ault Init (receiver, Ctrl) ; 



somDefaultlnit Parameter - receiver 



receiver (SOMObject) 

A pointer to an object of type SOMObject. 



somDefaultlnit Parameter - Ctrl 



Ctrl (somlnitCtrl) 

A pointer to a somlnitCtrl data structure. SOMobjects uses this data structure to control the initialization of the ancestor classes, 
thereby ensuring that no ancestor class receives multiple initialization calls. A pointer to a class that is an ancestor of the actual class 
of the receiver. 



somDefaultlnit Parameter - rc 



somDefaultlnit - Parameters 



receiver (SOMObject) 

A pointer to an object of type SOMObject. 



Ctrl (somlnitCtrl) 

A pointer to a somlnitCtrl data structure. SOMobjects uses this data structure to control the initialization of the ancestor classes, 
thereby ensuring that no ancestor class receives multiple initialization calls. A pointer to a class that is an ancestor of the actual class 
of the receiver. 



rc 



somDefaultlnit - Remarks 



Every SOM class is expected to support a set of initializer methods. This set will always include somDefaultlnit, whether or not the class 
explicitly overrides somDefaultlnit. All other initializer methods for a class must be explicitly introduced by the class. See Section 5.5, 
"Initializing and Uninitializing Objects," of the SOMoJects Deve/oper Too/k/t Users Guide for complete information on introducing new 
initializers. 

The purpose of an initializer method supported by a class is first to invoke initializer methods of ancestor classes (those ancestors that are 
the class's directinitclasses) and then to place the instance variables and attributes introduced by the class into some consistent state by 
loading them with appropriate values. The result is that, when an object is initialized, each class that contributes to its implementation will 
run some initializer method. The somDefaultlnit method may or may not be among the initializers used to initialize a given object, but it is 
always available for this purpose. 

Thus, the somDefaultlnit method may be invoked on a newly created object to initialize its instance variables and attributes. The 
somDefaultlnit method is more efficient than somlnit (the method it replaces), and it also prevents multiple initializer calls to ancestor 
classes. The somlnit method is now considered obsolete when writing new code, although somlnit is still supported. 

To override somDefaultlnit, the implementation section of the class's .idl file should include somDefaultlnit with the override and init 
modifiers specified. (The init modifier signifies that the method is an initializer method.) No additional coding is required for the resulting 
somDefaultlnit stub procedure in the implementation template file, unless the class implementor wishes to customize object initialization in 
some way. 

If the .idl file does not explicitly override somDefaultlnit, then by default a generic method procedure for somDefaultlnit will be provided by 
the SOMobjects Toolkit. If invoked, this generic method procedure first invokes somDefaultlnit on the appropriate ancestor classes, and 
then (for consistency with earlier versions of SOMobjects) calls any somlnit code that may have been provided by the class (if somlnit was 
overridden). Because the generic procedure for somDefaultlnit is less efficient than the stub procedure that is provided when 
somDefaultlnit is overridden, it is recommended that the .idl file always override somDefaultlnit. 

Note: It is not appropriate to override both somDefaultlnit and somlnit. If this is done, the somlnit code will not be executed. The best way 
to convert an old class that overrides somlnit to use of the more efficient somDefaultlnit (if this is desired) is as follows: (1) Replace the 
somlnit override in the class's .idl file with an override for somDefaultlnit, (2) run the implementation template emitter to produce a stub 
procedure for somDefaultlnit, and then (3) simply call the class's somlnit procedure directly (not using a method invocation) from the 
somDefaultlnit method procedure. 

As mentioned above, the object#initialization framework supported by SOMobjects allows a class to support additional initializer methods 
besides somDefaultlnit. These additional initializers will typically include special#purpose arguments, so that objects of the class can be 
initialized with special capabilities or characteristics. For each new initializer method, the implementation section must include the method 
name with the init modifier. Also, the directinitclasses modifier can be used if, for some reason, the class implementor wants to control the 
order in which ancestor initializers are executed. 

Note: It is recommended that the method name for an initializer method include the class name as a prefix. A newly defined initializer 
method will include an implicit Environment argument if the class does not use a callstyle=oidl modifier. 

Important: There are important constraints associated with modification of the procedure stubs for initializers. These are documented in 
Section 5.5 of the SOMobjects Deve/oper Too/k/t Users Gu/de. 



somDefaultlnit - Original Class 

SOMObject 



somDefaultlnit - Related Methods 

Methods 

• somDestruct 



somDefaultlnit - Example Code 




// SOM IDL 

#include <Animal.idl> 



interface Dog : Animal 
{ 



implementation { 

releaseorder : ; 

somDefaultlnit : 



override. 



init ; 



(null) 

Original Class 



somDefaultlnit - Topics 



Select an item: 
Syntax 
Parameters 
Returns 
Remarks 
Original Class 
Example Code 
Related Methods 
Glossary 



somDestruct 



somDestruct - Syntax 



This method uninitializes the receiving object, and (if so directed) frees object storage after uninitialization has been completed. Replaces 
somUninit as the preferred method for uninitializing objects. For performance reasons, it is recommended that somDestruct always be 
overridden. Not normally invoked directly by object clients. 



SOMObject 

octet 

somDestruct Ctrl 



receiver; 
dof ree; 

Ctrl; /* . */ 



somDestruct (receiver, dofree, Ctrl); 



somDestruct Parameter - receiver 



receiver (SOMObject) 

A pointer to an object. 



somDestruct Parameter - dofree 



dofree (octet) 

A boolean indicating whether the caller wants the object storage freed after uninitialization of the current class has been completed. 
Passing 1 (true) indicates the object storage should be freed. 



somDestruct Parameter - Ctrl 



Ctrl (somDestructCtrl) 

A pointer to a somDestructCtrl data structure. SOMobjects uses this data structure to control the uninitialization of the ancestor 
classes, thereby ensuring that no ancestor class receives multiple uninitialization calls, if a user invokes somDestruct on an object 
directly, a NULL (that is, zero) Ctrl pointer can be passed. This instructs the receiving code to obtain a somDestructCtrl data 
structure from the class of the object. 



somDestruct Parameter - rc 



somDestruct - Parameters 



receiver (SOMObject) 

A pointer to an object. 

dofree (octet) 

A boolean indicating whether the caller wants the object storage freed after uninitialization of the current class has been completed. 
Passing 1 (true) indicates the object storage should be freed. 

Ctrl (somDestructCtrl) 

A pointer to a somDestructCtrl data structure. SOMobjects uses this data structure to control the uninitialization of the ancestor 
classes, thereby ensuring that no ancestor class receives multiple uninitialization calls, if a user invokes somDestruct on an object 
directly, a NULL (that is, zero) Ctrl pointer can be passed. This instructs the receiving code to obtain a somDestructCtrl data 
structure from the class of the object. 



rc 




somDestruct - Remarks 



Every class must support the somDestruct method. This is accomplished either by overriding somDestruct (in which case a specialized 
stub procedure will be generated in the implementation template file), or else SOMobjects will automatically provide a generic procedure 
that implements somDestruct for the class. The generic procedure calls somllninit (if this was overridden) to perform local uninitialization, 
then completes execution of the method appropriately. 

Because the specialized stub procedure generated by the template emitter is more efficient than the generic procedure provided when 
somDestruct is not overridden, it is recommended that somDestruct always be overridden. The stub procedure that is generated in this 
case requires no modification for correct operation. The only modification appropriate within this stub procedure is to uninitialize locally 
introduced instance variables. See Section 5.5, "Initializing and Unitializing Objects," of the SOMobjects Deve/oper Too/kit Users Guide for 
further details. 

Uninitialization with somDestruct executes as follows: For any given class in the ancestor chain, somDestruct first uninitializes that class's 
introduced instance variables (if this is appropriate), and then calls the next ancestor class's implementation of somDestruct, passing 0 
(that is, false) as the interim dofree argument. Then, after all ancestors of the given class have been uninitialized, if the class's own 
somDestruct method were originally invoked with dofree as 1 (that is, true), then that object's storage is released. 

Note: It is not appropriate to override both somDestruct and somUninit. If this is done, the somUninit code will not be executed. The best 
way to convert an old class that overrides somUninit to use of the more efficient somDestruct (if this is desired) is as follows: (1) Replace 
the somUninit override in the class's .idl file with an override for somDestruct, (2) run the emitter to produce a stub procedure for 
somDestruct in the implementation template file, and then (3) simply call the class's somUninit procedure directly (not using a method 
invocation) from the somDestruct procedure. 



somDestruct - Original Class 



SOMObject 



somDestruct - Related Methods 



Functions 

* somDefaultlnit 



somDestruct - Example Code 



// SOM IDL 

#include <Animal.idl> 

interface Dog : Animal 
{ 

implementation { 

releaseorder : ; 

somDestruct: override; 




somDestruct - Topics 



Select an item: 
Syntax 
Parameters 
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somDispatch 



somDispatch - Syntax 



Invokes a method using dispatch method resolution. The somDispatch method is designed to be overridden. The somClassDispatch 
method is not generally overridden. 

For backward compatibility, this method does not take an Environment parameter. 



SOMObject 

somToken 

somID 

va_list 

boolean 



receiver; 

retValue; 

methodld; 

args; 

rc; 



rc = somDispatch (receiver , retValue, methodld, 
args) ; 



somDispatch Parameter - receiver 



receiver (SOMObject) 

A pointer to the object whose class will be used for method resolution by somDispatch. 



somDispatch Parameter - retValue 



retValue (somToken) 



The address of the area in memory where the result of the invoked method procedure is to be stored. The caller is responsible for 
allocating enough memory to hold the result of the specified method. When dispatching methods that return no result (i.e., void), a 
NULL may be passed as this argument. 



somDispatch Parameter - methodic! 



methodld (somID) 

A somld identifying the method to be invoked. A string representing the method name can be converted to a somld using the 
somldFromString function. 



somDispatch Parameter - args 



args (vajist) 

A vajist containing the arguments to be passed to the method identified by method/d. The arguments must include a pointer to the 
target object as the first entry. As a convenience for C and C++ programmers, SOM's language bindings provide a varargs invocation 
macro for vajist methods (such as somDispatch and somClassDispatch). The example below illustrates this. 



somDispatch Parameter - rc 



rc (boolean) 

A boolean representing whether or not the method was successfully dispatched is returned. The reason for this is that somDispatch 
and somClassDispatch use the function somApply to invoke the resolved method procedure, and somApply requires an apply 
stub for successful execution. In support of old class binaries SOM does not consider a NULL apply stub to be an error. As a result, 
somApply may fail, if this happens, then false is returned; otherwise true is returned. 



somDispatch - Parameters 



receiver (SOMObject) 

A pointer to the object whose class will be used for method resolution by somDispatch. 
retValue (somToken) 

The address of the area in memory where the result of the invoked method procedure is to be stored. The caller is responsible for 
allocating enough memory to hold the result of the specified method. When dispatching methods that return no result (i.e., void), a 
NULL may be passed as this argument. 

methodld (somID) 

A somld identifying the method to be invoked. A string representing the method name can be converted to a somld using the 
somldFromString function. 

args (vajist) 

A vajist containing the arguments to be passed to the method identified by method/d. The arguments must include a pointer to the 
target object as the first entry. As a convenience for C and C++ programmers, SOM's language bindings provide a varargs invocation 
macro for vajist methods (such as somDispatch and somClassDispatch). The example below illustrates this. 




rc (boolean) 

A boolean representing whether or not the method was successfully dispatched is returned. The reason for this is that somDispatch 
and somClassDispatch use the function somApply to invoke the resolved method procedure, and somApply requires an apply 
stub for successful execution. In support of old class binaries SOM does not consider a NULL apply stub to be an error. As a result, 
somApply may fail. If this happens, then false is returned; otherwise true is returned. 



somDispatch - Remarks 



somDispatch and somClassDispatch perform method resolution to select a method procedure, and then invoke this procedure on args. 
The somSelf argument for the selected method procedure (called the target object , below, to distinguish it from the receiver of the 
somDispatch or somClassDispatch method call) is the first argument included in the vajist, args. 

For somDispatch, method resolution is performed using the class of the receiver; for somClassDispatch, method resolution is performed 
using the argument class, c/sObj . Because somClassDispatch uses c/sObj for method resolution, a programmer invoking somDispatch 
or somClassDispatch should assure that the class of the target object is either derived from or is identical to the class used for method 
resolution; otherwise, a runtime error will likely result when the target object is passed to the resolved procedure. Although not necessary, 
the receiver is usually also the target object. 

The somDispatch and somClassDispatch methods supersede the somDispatch^T methods. Unlike the somDispatch^ methods, which 
are restricted to few return types, the somDispatch and somClassDispatch methods make no assumptions concerning the result returned 
by the method to be invoked. Thus, somDispatch and somClassDispatch can be used to invoke methods that return structures. The 
somDispatch^ methods now invoke somDispatch, so overriding somDispatch serves to override the somDispatch^ methods as well. 



somDispatch - Original Class 

SOMObject 



somDispatch - Related Methods 

Functions 

• somApply 



somDispatch - Example Code 



Given class Key that has an attribute keyva/ of type long and an overridden method for somPrintSelf that prints the value of the attribute 
(as well as the information printed by SOMObject's implementation of somPrintSelf), the following client code invokes methods on Key 
objects using somDispatch and somClassDispatch. (The Key class was defined with the callstyle=oidl class modifier, so the 
Environment argument is not required of its methods.) 

ftinclude <key.h> 

main ( ) 

{ 

SOMObject obj; 
long kl = 7, k2; 

Key *myKey = KeyNewO; 
somVaBuf vb; 
va_list push, args; 




somld setld = somldFromString ( "_set_keyval" ) ; 
somld getld = somldFromString ( "_get_keyval" ) ; 
somld prtld = somldFromString (" somPrintSelf " ) ; 

vb = (somVaBuf ) somVaBuf_create (NULL, 0); 
somVaBuf_add (vb, (char *)&myKey, tk_ulong); 
somVaBuf_add (vb, (char *)&kl, tk_long) ; 
somVaBuf_get_valist (vb, &args) ; 



/* va_list invocation of setkey and getkey */ 

SOMOb ject_somDispatch (myKey, (somToken *)0, setld, args); 
somVaBuf_get_valist (vb, &args) ; 

SOMOb ject_somDispatch (myKey, (somToken *)&k2, getld, args); 
print f ( "va_list _set_keyval and _get_keyval : %i\n", k2) ; 

/* varargs invocation of setkey and getkey */ 

_s omDi spat ch (myKey, (somToken *)0, setld, myKey, kl) ; 

_s omDi spat ch (myKey, (somToken *)&k2, getld, myKey); 
print f ( "varargs _set_keyval and _get_keyval : %i\n", k2) ; 

/* illustrate somClassDispatch "casting" (use varargs form) */ 
print f ( "somPrintSelf on myKey as a Key:\n"); 

_somClassDispatch (myKey, _Key, (somToken *)&obj, prtld, myKey, 0); 
printf ( "somPrintSelf on myKey as a SOMOb ject : \n" ) ; 

_somClassDispatch (myKey, _SOMObject, (somToken *)&obj, prtld, myKey, 0) 

SOMFree (setld) ; 

SOMFree (getld) ; 

SOMFree (prtld) ; 

_somFree (myKey) ; 

somVaBuf_destroy (vb) ; 

} 



This program produces the following output: 



va_list _set_keyval and _get_keyval : 
varargs _set_keyval and _get_keyval : 
somPrintSelf on myKey as a Key: 

{An instance of class Key at address 
— with key value 7 
somPrintSelf on myKey as a SOMOb ject: 
{An instance of class Key at address 



7 

7 

2005B2F8 } 
2005B2F8 } 



somDispatch - Topics 
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somClassDispatch 



somClassDispatch - Syntax 



Invokes a method using dispatch method resolution. The somDispatch method is designed to be overridden. The somClassDispatch 
method is not generally overridden. 

For backward compatibility, this method does not take an Environment parameter. 



SOMObject 

SOMClass 

somToken 

somID 

va_list 

boolean 



receiver; 

clsObj; 

retValue; 

methodld; 

args; 

rc; 



rc 



somClassDispatch (receiver, 
methodld, args) ; 



clsObj, retValue, 



somClassDispatch Parameter - receiver 



receiver (SOMObject) 

A pointer to the object whose class will be used for method resolution by somDispatch. 



somClassDispatch Parameter - clsObj 



clsObj (SOMClass) 

A pointer to the class that will be used for method resolution by somClassDispatch. 



somClassDispatch Parameter - retValue 



retValue (somToken) 

The address of the area in memory where the result of the invoked method procedure is to be stored. The caller is responsible for 
allocating enough memory to hold the result of the specified method. When dispatching methods that return no result (i.e., void), a 
NULL may be passed as this argument. 



somClassDispatch Parameter - methodic! 



methodld (somID) 



A somld identifying the method to be invoked. A string representing the method name can be converted to a somld using the 
somldFromString function. 



somClassDispatch Parameter - args 



args (vajist) 

A vajist containing the arguments to be passed to the method identified by method/d. The arguments must include a pointer to the 
target object as the first entry. As a convenience for C and C++ programmers, SOM's language bindings provide a varargs invocation 
macro for vajist methods (such as somDispatch and somClassDispatch). The example below illustrates this. 



somClassDispatch Parameter - rc 



rc (boolean) 

A boolean representing whether or not the method was successfully dispatched is returned. The reason for this is that somDispatch 
and somClassDispatch use the function somApply to invoke the resolved method procedure, and somApply requires an apply 
stub for successful execution. In support of old class binaries SOM does not consider a NULL apply stub to be an error. As a result, 
somApply may fail. If this happens, then false is returned; otherwise true is returned. 



somClassDispatch - Parameters 



receiver (SOMObject) 

A pointer to the object whose class will be used for method resolution by somDispatch. 
clsObj (SOMCIass) 

A pointer to the class that will be used for method resolution by somClassDispatch. 
retValue (somToken) 

The address of the area in memory where the result of the invoked method procedure is to be stored. The caller is responsible for 
allocating enough memory to hold the result of the specified method. When dispatching methods that return no result (i.e., void), a 
NULL may be passed as this argument. 

methodld (somID) 

A somld identifying the method to be invoked. A string representing the method name can be converted to a somld using the 
somldFromString function. 

args (vajist) 

A vajist containing the arguments to be passed to the method identified by method/d. The arguments must include a pointer to the 
target object as the first entry. As a convenience for C and C++ programmers, SOM's language bindings provide a varargs invocation 
macro for vajist methods (such as somDispatch and somClassDispatch). The example below illustrates this. 

rc (boolean) 

A boolean representing whether or not the method was successfully dispatched is returned. The reason for this is that somDispatch 
and somClassDispatch use the function somApply to invoke the resolved method procedure, and somApply requires an apply 
stub for successful execution. In support of old class binaries SOM does not consider a NULL apply stub to be an error. As a result, 
somApply may fail. If this happens, then false is returned; otherwise true is returned. 



somClassDispatch - Remarks 




somDispatch and somClassDispatch perform method resolution to select a method procedure, and then invoke this procedure on args . 
The somSelf argument for the selected method procedure (called the target object , below, to distinguish it from the receiver of the 
somDispatch or somClassDispatch method call) is the first argument included in the vajist, args. 

For somDispatch, method resolution is performed using the class of the receiver; for somClassDispatch, method resolution is performed 
using the argument class, c/sObj . Because somClassDispatch uses c/sObj for method resolution, a programmer invoking somDispatch 
or somClassDispatch should assure that the class of the target object is either derived from or is identical to the class used for method 
resolution; otherwise, a runtime error will likely result when the target object is passed to the resolved procedure. Although not necessary, 
the receiver is usually also the target object. 

The somDispatch and somClassDispatch methods supersede the somDispatch^T methods. Unlike the somDispatch^ methods, which 
are restricted to few return types, the somDispatch and somClassDispatch methods make no assumptions concerning the result returned 
by the method to be invoked. Thus, somDispatch and somClassDispatch can be used to invoke methods that return structures. The 
somDispatch.^'' methods now invoke somDispatch, so verriding somDispatch serves to override the somDispatchxT methods as well. 



somClassDispatch - Original Class 

SOMObject 



somClassDispatch - Related Methods 

Functions 

• somApply 



somClassDispatch - Example Code 



Given class Key that has an attribute keyva/ of type long and an overridden method for somPrintSelf that prints the value of the attribute 
(as well as the information printed by SOMObject's implementation of somPrintSelf), the following client code invokes methods on Key 
objects using somDispatch and somClassDispatch. (The Key class was defined with the callstyle=oidl class modifier, so the 
Environment argument is not required of its methods.) 



#include <key.h> 



main ( ) 

{ 

SOMObject obj; 
long kl = 7, k2; 

Key *myKey = KeyNew ( ) ; 
somVaBuf vb; 
va_list push, args; 



somld setld = 
somld getld = 
somld prtld = 



somldFromString ( "_set_keyval " ) ; 
somldFromString ( "_get_keyval " ) ; 
somldFromString ( " somPrintSelf" ) ; 



vb = (somVaBuf ) somVaBuf_create (NULL, 0); 
somVaBuf_add (vb, (char *)&myKey, tk_ulong) ; 
somVaBuf_add (vb, (char *)&kl, tk_long) ; 
somVaBuf_get_valist (vb, &args) ; 



/* va_list invocation of setkey and getkey */ 

SOMOb ject_somDispatch (myKey, (somToken *)0, setld, args); 
somVaBuf_get_valist (vb, &args) ; 




SOMOb ject_somDispatch (myKey, (somToken *)&k2, getld, args) ; 
print f ( "va_list _set_keyval and _get_keyval : %i\n", k2) ; 

/* varargs invocation of setkey and getkey */ 

_s omDi spat ch (myKey, (somToken *)0, setld, myKey, kl) ; 

_s omDi spat ch (myKey, (somToken *)&k2, getld, myKey); 
print f ( "varargs _set_keyval and _get_keyval : %i\n" , k2) ; 

/* illustrate somClassDispatch "casting" (use varargs form) */ 
print f ( "somPrintSelf on myKey as a Key:\n"); 

_somClassDispatch (myKey, _Key, (somToken *)&obj, prtld, myKey, 0) ; 
printf ( "somPrintSelf on myKey as a SOMOb ject : \n" ) ; 

_somClassDispatch (myKey, _SOMObject, (somToken *)&obj, prtld, myKe 

SOMFree (setld) ; 

SOMFree (getld) ; 

SOMFree (prtld) ; 

_somFree (myKey) ; 

somVaBuf_destroy (vb) ; 

} 



This program produces the following output: 



va_list _set_keyval and _get_keyval : 
varargs _set_keyval and _get_keyval : 
somPrintSelf on myKey as a Key: 

{An instance of class Key at address 
— with key value 7 
somPrintSelf on myKey as a SOMObject 
{An instance of class Key at address 



7 

7 
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somDumpSelf 



somDumpSelf - Syntax 



This method writes out a detailed description of the receiving object. Intended for use by object clients. Not generally overridden. Note: For 
backward compatibility, this method does not take and Environment parameter. 



SOMObject 

long 



receiver; 

level; 



somDumpSelf (receiver, level) ; 



somDumpSelf Parameter - receiver 



receiver (SOMObject) 

A pointer to the object to be dumped. 



somDumpSelf Parameter - level 



level (long) 

The nesting level for describing compound objects. It must be greater than or equal to 0. All lines in the description will be preceded 
by "2 * level" spaces. 



somDumpSelf Parameter - rc 



somDumpSelf - Parameters 



receiver (SOMObject) 

A pointer to the object to be dumped. 



level (long) 

The nesting level for describing compound objects. It must be greater than or equal to 0. All lines in the description will be preceded 
by "2 * level" spaces. 



rc 



somDumpSelf - Remarks 



The somDumpSelf method performs some initial setup, and then invokes the somDumpSelflnt method to write a detailed description of 
the receiver, including its state. 



somDumpSelf - Original Class 

SOMOBject 



somDumpSelf - Related Methods 

Methods 

* somDumpSelflnt 



somDumpSelf - Topics 
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somDumpSelflnt 



somDumpSelflnt - Syntax 



This method outputs the internal state of an object. Intended to be overridden by class implementors. Not intended to be directly invoked by 
object clients. 

For backward compatibility, this method does not take an Environment parameter. 



SOMObject receiver; 

long level; 

somDumpSelf Int (receiver , level); 



somDumpSelflnt Parameter - receiver 



receiver (SOMObject) 

A pointer to the object to be dumped. 



somDumpSelflnt Parameter - level 



level (long) 

The nesting level for describing compound objects. It must be greater than or equal to 0. All lines in the description should be 
preceded by "2* level" spaces. 



somDumpSelflnt Parameter - rc 



somDumpSelflnt - Parameters 



receiver (SOMObject) 

A pointer to the object to be dumped. 



level (long) 

The nesting level for describing compound objects. It must be greater than or equal to 0. All lines in the description should be 
preceded by "2* level" spaces. 



rc 



somDumpSelflnt - Remarks 



The somDumpSelflnt method should be overridden by a class implementor, to write out the instance data stored in an object. This method 
is invoked by the somDumpSelf method, which is used by object clients to output the state of an object. 

The procedure used to override this method for a new class should begin by calling the parent class form of this method on each of the class 
parents, and should then write a description of the instance variables introduced by new class. This will result in a description of all the 
class's instance variables. The C and C++ implementation bindings provide a convenient macro for performing parent method calls on all 
parents, as illustrated below. 

The character output routine pointed to by SOMOutCharRoutine should be used for output. The somLPrintf function is especially 
convenient for this, since level is handled appropriately. 



somDumpSelflnt - Original Class 




SOMObject 



somDumpSelflnt - Related Methods 



Methods 

• somDumpSelf 

• somPrintSelf 



somDumpSelflnt - Example Code 



Below is a method overriding somDumpSelflnt for class "List", which has two attributes, va/ (which is a long) and next (which is a pointer 
to a "List" object). 

SOM_Scope void SOMLINK somDumpSelf Int (List somSelf, int level) 

{ 

ListData *somThis = ListGetData (somSelf ) ; 

Environment *ev = somGetGlobalEnvironment ( ) ; 

List_parents_somDumpSelf Int (somSelf , level) ; 

somLPrintf (level, "This item: %i\n", get_val (somSelf , ev) ; 

somLPrintf (level, "Next item: \n"); 

if ( get_next (somSelf , ev) != (List) NULL) 

_somDumpSelf Int ( get_next (somSelf, ev) , level+1) ; 

else 

somLPrintf (level+1, "NULL\n") ; 

} 



Below is a client program that invokes the somDumpSelf method on "List" objects. 

#include <list.h> 

main ( ) 

{ 

List LI, L2; 
long x = 7, y = 13; 

Environment *ev = somGetGlobalEnvironment () ; 

LI = ListNew ( ) ; 

L2 = ListNew ( ) ; 

set_val(Ll, ev, x) ; 

set_next (LI , ev, (List) NULL); 

set_val(L2, ev, y) ; 

set_next (L2 , ev, LI); 

_somDumpSelf (L2, 0) ; 

_somFree (LI ) ; 

_somFree (L2 ) ; 

} 



Below is the output produced by this program: 

{An instance of class List at 0x2005EA8 
This item: 13 
Next item: 

1 This item: 7 
1 Next item: 

2 NULL 




somDumpSelflnt - Topics 



Select an item: 
Syntax 
Parameters 
Returns 
Remarks 
Original Class 
Example Code 
Related Methods 
Glossary 



somFree 



somFree - Syntax 



This method releases the storage used by an object. Intended for use by object clients. Not generally overridden. 
For backward compatibility, this method does not take an Environment parameter. 

SOMObject receiver; 
somFree (receiver) ; 



somFree Parameter - receiver 



receiver (SOMObject) 

A pointer to the object to be freed. 



somFree Parameter - rc 



somFree - Parameters 



receiver (SOMObject) 

A pointer to the object to be freed. 



rc 



somFree - Remarks 



The somFree method releases the storage containing the receiver object by calling the method somDeallocate. No future references 
should be made to the receiver once this is done. The somFree method calls somDestruct to allow storage pointed to by the object to be 
freed. 

The somFree method should not be called on objects created by somRenew, thus the method is normally only used by code that also 
created the object. 

Note: SOM also supplies a macro, SOMFree, which is used to free a block of memory. This macro should not be used on objects. 



somFree - Original Class 

SOMObject 



somFree - Related Methods 

Methods 

• somNew 

• somNewNolnit 

• somDestruct 

Functions 

• SOMFree 



somFree - Example Code 



#include <animal.h> 

void main ( ) 

{ 




An ima 1 myAn ima 1 ; 

/* 

* Create an object. 

*/ 

myAnimal = AnimalNew(); 

/* ... */ 

/* Free it when finished. */ 
_somFree (myAnimal) ; 

} 



somFree - Topics 



Select an item: 
Syntax 
Parameters 
Returns 
Remarks 
Original Class 
Example Code 
Related Methods 
Glossary 



somGetClass 



somGetClass - Syntax 



This method returns a pointer to an object's class object. Not generally overridden. 
For backward compatibility, this method does not take an Environment parameter. 

SOMObject receiver; 

SOMClass rc; 

rc = somGetClass (receiver) ; 



somGetClass Parameter - receiver 



receiver (SOMObject) 

A pointer to the object whose class is desired. 



somGetClass Parameter - rc 



rc (SOMCIass) 

A pointer to the object's class object. This return value is cast as a (SOMCIass*). In C++, you may have to explicitly cast this to a 
pointer of a specific class type (when different from SOMCIass). 



somGetClass - Parameters 



receiver (SOMObject) 

A pointer to the object whose class is desired, 
rc (SOMCIass) 

A pointer to the object's class object. This return value is cast as a (SOMCIass*). In C++, you may have to explicitly cast this to a 
pointer of a specific class type (when different from SOMCIass). 



somGetClass - Remarks 



somGetClass obtains a pointer to the receiver's class object. The somGetClass method is typically not overridden. 

Important Note: For C and C++ programmers, SOM provides a SOM_GetClass macro that performs the same function. This macro should 
only be used only when absolutely necessary (i.e., when a method call on the object is not possible), since it bypasses whatever semantics 
may be intended for the somGetClass method by the implementor of the receiver's class. Even class implementors do not know whether a 
special semantics for this method is inherited from ancestor classes. If you are unsure of whether the method or the macro is appropriate, 
you should use the method call. 



somGetClass - Original Class 



SOMObject 



somGetClass - Related Methods 



Methods 

• SOMGetClass 



somGetClass - Example Code 




#include <animal.h> 
main ( ) 

{ 

An ima 1 myAn ima 1 ; 
int numMethods; 

SOMClass animalClass; 

myAnimal = AnimalNew (); 

animalClass = _somGetClass (myAnimal) ; 

SOM_Test (animalClass == _Animal) ; 



somGetClass - Topics 



Select an item: 
Syntax 
Parameters 
Returns 
Remarks 
Original Class 
Example Code 
Related Methods 
Glossary 



somGetClassName 



somGetClassName - Syntax 



This method returns the name of the class of an object. Not generally overridden. 
For backward compatibility, this method does not take an Environment parameter. 



somObject receiver; 

string rc; 

rc = somGetClassName (receiver) ; 



somGetClassName Parameter - receiver 



receiver (somObject) 

A pointer to the object whose class name is desired. 



somGetClassName Parameter - rc 



rc (string) 

Returns a pointer to the name of the class. 



somGetClassName - Parameters 



receiver (somObject) 

A pointer to the object whose class name is desired, 
rc (string) 

Returns a pointer to the name of the class. 



somGetClassName - Remarks 



The somGetClassName method returns a pointer to a zero-terminated string that gives the name of the class of an object. 

This method is not generally overridden; it simply invokes somGetName on the class of the receiver. Refer to somGetName for more 
information on the returned string. 



somGetClassName - Original Class 

SOMObject 



somGetClassName - Related Methods 

Methods 

• somGetName 



somGetClassName - Example Code 




#include <animal.h> 
main ( ) 

{ 

An ima 1 myAn ima 1 ; 

SOMClass animalClass; 
char *className; 

myAnimal = AnimalNew(); 

className = _somGetClassName (myAnimal) ; 
somPrintf ( "Class name: %s\n", className); 
_somFree (myAnimal) ; 



/* 

Output from this program: 
Class name: Animal 

*/ 



somGetClassName - Topics 



Select an item: 
Syntax 
Parameters 
Returns 
Remarks 
Original Class 
Example Code 
Related Methods 
Glossary 



somGetSize 



somGetSize - Syntax 



This method returns the size of an object. Not generally overridden. 

For backward compatibility, this method does not take an Environment parameter. 

SOMObject receiver; 

long rc; 

rc = somGetSize (receiver) ; 



somGetSize Parameter - receiver 



receiver (SOMObject) 

A pointer to the object whose size is desired. 



somGetSize Parameter - rc 



rc (long) 

Returns the size, in bytes, of the receiver. 



somGetSize - Parameters 



receiver (SOMObject) 

A pointer to the object whose size is desired, 
rc (long) 

Returns the size, in bytes, of the receiver. 



somGetSize - Remarks 



The somGetSize method returns the total amount of contiguous space used by the receiving object. 

The value returned reflects only the amount of storage needed to hold the SOM representation of the object. The object might actually be 
using or managing additional space outside of this area. 

The somGetSize method is not generally overridden. 



somGetSize - Original Class 

SOMObject 



somGetSize - Related Methods 



Methods 



somGetlnstancePartSize 

somGetlnstanceSize 



somGetSize - Example Code 




#include <animal.h> 
void main ( ) 

{ 

An ima 1 my An ima 1 ; 

long animalSize; 

my Animal = AnimalNew(); 

animalSize = _somGetSize (my Animal ) ; 

somPrintf ( "Size of animal (in bytes) : %d\n", animalSize); 
_somFree (my Animal) ; 



/* 

Output from this program: 
Size of animal (in bytes) : 8 
*/ 



somGetSize - Topics 



Select an item: 
Syntax 
Parameters 
Returns 
Remarks 
Original Class 
Example Code 
Related Methods 
Glossary 



somlnit 



somlnit - Syntax 



This method initializes instance variables or attributes in a newly created object. Designed to be overridden. Note: The newer 
somDefaultlnit method is suggested instead. 

For backward compatibility, this method does not take an Environment parameter. 

SOMObject receiver; 
somlnit (receiver) ; 



somlnit Parameter - receiver 



receiver (SOMObject) 

A pointer to the object to be initialized. 



somlnit Parameter - rc 



somlnit - Parameters 



receiver (SOMObject) 

A pointer to the object to be initialized. 



rc 



somlnit - Remarks 



The somlnit method is invoked to cause a newly created object to initialize its instance variables or attributes. 

Note: The newer somDefaultlnit method performs object initialization more efficiently and is now the preferred approach for overriding 
initialization in an implementation file. (The somlnit method still executes correctly as before.) 

Because instances of SOMObject do not have any instance data, the default implementation does nothing. It is provided as a convenience 
to class implementors so that initialization of objects can be done in a uniform way across all classes (by overriding somlnit). This method is 
called automatically by somNew during object creation. 

A companion method, somllninit, is called whenever an object is freed. These two methods should be designed to work together, with 
somlnit priming an object for its first use, and somllninit preparing the object for subsequent release. 

If objects of your class contain instance variables or attributes, override the somlnit method to initialize the instance variables or attributes 
when instances of the class are created. When overriding this method, always call all parent (base) classes' versions of this method 
A?/&/i?doing your own initialization, as follows: 

1 . The overriding implementation should invoke the parent method for each parent. For users of the C or C++ implementation bindings, this 
can be done in either of two ways: (a) by calling a _parents_ macro (which automatically invokes all parent methods) or (b) by calling the 
_parent_ parentName> _ macro on each parent separately. 

For more information on parent method calls, see the topic "Extending the Implementation Template 1 ' in Chapter 5, "Implementing Classes in 
SOM," of the SOM Too/k/t User's Gu/de. 

2. The code must be written so that it can be executed multiple times without harm on the same object. This is necessary because, under 
multiple inheritance, parent method calls that progress up the inheritance hierarchy may encounter the same ancestor class more than once 
(where different inheritance paths "join” when followed backward). A check can be made to determine whether a particular invocation of 
somlnit is the first on a given object by examining the contents of its instance variables; all the instance variables and attributes of a newly 
created SOM object are set to zero before somlnit is invoked on that object. 

More information and examples on object initialization (especially regarding the somDefaultlnit method) are given in the topic "Initializing 
and Uninitializing Objects" in Chapter 5, "Implementing Classes in SOM," of the SOM Too/k/t User's Guide. 




somlnit - Original Class 

SOMObject 



somlnit - Related Methods 



Methods 



somDefaultlnit 

somNew 
som Renew 
somDestruct 
somUninit 



somlnit - Example Code 



Below is the implementation for a class An/ma/ that introduces an attribute sound of type string and overrides somlnit and somUninit, 
along with a main program that creates and then frees an instance of class An/ma/. 

#define Animal_Class_Source 
#include <animal.ih> 

#include <string.h> 

SOM_Scope void SOMLINK somlnit (Animal somSelf) 

{ 

AnimalData *somThis = AnimalGetData (somSelf ) ; 

Environment *ev = somGetGlobalEnvironment ( ) ; 

Animal_parents_somInit (somSelf) ; 

if (! get_sound (somSelf , ev) ) { 

set_sound (somSelf , ev, SOMMalloc ( 100 ) ) ; 

strcpy ( get_sound (somSelf , ev) , "Unknown Noise"); 

somPrintf ("New Animal Initialized\n" ) ; 




SOM_Scope void SOMLINK somUninit (Animal somSelf) 

{ 

AnimalData *somThis = AnimalGetData (somSelf) ; 
Environment *ev = somGetGlobalEnvironment () ; 

if ( get_sound (somSelf , ev) ) { 

SOMFree ( get_sound ( somSelf , ev) ; 

set_sound (somSelf , ev, (char*)0); 

somPrintf ("Animal Uninitialized\n" ) ; 
Animal_parents_somUninit (somSelf) ; 




/* main program */ 

#include <animal.h> 
void main ( ) 

{ 

An ima 1 my An ima 1 ; 
my Animal = AnimalNew (); 
_somFree (my Animal) ; 

} 



/* 

Program output: 




New Animal Initialized 
Animal Uninitialized 
*/ 



somlnit - Topics 



Select an item: 
Syntax 
Parameters 
Returns 
Remarks 
Original Class 
Example Code 
Related Methods 
Glossary 



somlsA 



somlsA - Syntax 



This method tests whether an object is an instance of a given class or of one of its descendant classes. Not generally overridden. 
For backward compatibility, this method does not take an Environment parameter. 



SOMObject 

SOMClass 

boolean 



receiver; 

aClass; 

rc; 



rc = somlsA (receiver , aClass) ; 



somlsA Parameter - receiver 



receiver (SOMObject) 

A pointer to the object to be tested. 



somlsA Parameter - aClass 



aClass (SOMCIass) 

A pointer to the class that the object should be tested against. 



somlsA Parameter - rc 



rc (boolean) 

Returns 1 (true) if the receiving object is an instance of the specified class or (unlike somlsInstanceOf) of any of its descendant 
classes, and 0 (false) otherwise. 



somlsA - Parameters 



receiver (SOMObject) 

A pointer to the object to be tested. 

aClass (SOMCIass) 

A pointer to the class that the object should be tested against, 
rc (boolean) 

Returns 1 (true) if the receiving object is an instance of the specified class or (unlike somlsInstanceOf) of any of its descendant 
classes, and 0 (false) otherwise. 



somlsA - Remarks 



Use the somlsA method to determine if an object can be treated like an instance of aC/ass. SOM guarantees that if somlsA returns true, 
then the receiver will respond to all (static or dynamic) methods supported by aC/ass. 



somlsA - Original Class 



SOMObject 



somlsA - Related Methods 



Methods 

• somlsDescendedFrom 

• somlsInstanceOf 

• somRespondsTo 

• somSupportsMethod 




somlsA - Example Code 



#include <dog.h> 

/* 

Note: Dog is derived from Animal. 

*/ 

main ( ) 

{ 

An ima 1 my An ima 1 ; 

Dog myDog; 

SOMClass animalClass; 

SOMClass dogClass; 

my Animal = AnimalNew(); 
myDog = DogNew ( ) ; 

animalClass = _somGetClass (myAnimal) ; 
dogClass = _somGetClass (myDog) ; 
if (_somIsA (myDog, animalClass) ) 

somPrintf ("myDog IS an Animal\n"); 
else 

somPrintf ("myDog IS NOT an Animal\n") 
if (_somIsA (myAnimal, dogClass) ) 

somPrintf ("myAnimal IS a Dog\n"); 
else 

somPrintf ("myAnimal IS NOT a Dog\n"); 
_somFree (myAnimal) ; 

_somFree (myDog) ; 



/* 

Output from this program: 
myDog IS an Animal 
myAnimal IS NOT a Dog 
*/ 



somlsA - Topics 



Select an item: 
Syntax 
Parameters 
Returns 
Remarks 
Original Class 
Example Code 
Related Methods 
Glossary 



somlsInstanceOf 



somlsInstanceOf - Syntax 



This method determines whether an object is an instance of a specific class. Not generally overridden. 



For backward compatibility, this method does not take an Environment parameter. 



SOMObject receiver; 

SOMClass aClass; 

boolean rc; 

rc = somlsInstanceOf (receiver , aClass); 



somlsInstanceOf Parameter - receiver 



receiver (SOMObject) 

A pointer to the object to be tested. 



somlsInstanceOf Parameter - aClass 



aClass (SOMClass) 

A pointer to the class that the object should be an instance of. 



somlsInstanceOf Parameter - rc 



rc (boolean) 

Returns 1 (true) if the receiving object is an instance of the specified class, and 0 (false) otherwise. 



somlsInstanceOf - Parameters 



receiver (SOMObject) 

A pointer to the object to be tested. 

aClass (SOMClass) 

A pointer to the class that the object should be an instance of. 
rc (boolean) 

Returns 1 (true) if the receiving object is an instance of the specified class, and 0 (false) otherwise. 



somlsInstanceOf - Remarks 



Use the somlsInstanceOf method to determine if an object is an instance of a specific class. This method tests an object for inclusion in 
one specific class. It is equivalent to the expression: 

(aClass == somGetClass (receiver) ) 



somlsInstanceOf - Original Class 

SOMObject 



somlsInstanceOf - Related Methods 



Methods 



somDescendedFrom 

somlsA 



somlsInstanceOf - Example Code 



#include <dog.h> 

/* 

Note: Dog is derived from Animal. 

*/ 

main ( ) 

{ 

Animal my Animal; 

Dog myDog; 

SOMClass animalClass; 

SOMClass dogClass; 

my Animal = AnimalNew (); 
myDog = DogNew ( ) ; 

animalClass = _somGetClass (my Animal) ; 
dogClass = _somGetClass (myDog) ; 
if (_somlslnstance0f (myDog, animalClass) ) 

somPrintf ("myDog is an instance of Animal\n"); 
if (_somlslnstance0f (myDog, dogClass) ) 

somPrintf ("myDog is an instance of Dog\n"); 
if (_somlslnstance0f (my Animal, animalClass) ) 

somPrintf ("myAnimal is an instance of Animal\n"); 
if (_somlslnstance0f (myAnimal, dogClass) ) 

somPrintf ("myAnimal is an instance of Dog\n"); 
_somFree (myAnimal) ; 

_somFree (myDog) ; 



/* 

Output from this program: 
myDog is an instance of Dog 
myAnimal is an instance of Animal 
*/ 




somlsInstanceOf - Topics 



Select an item: 
Syntax 
Parameters 
Returns 
Remarks 
Original Class 
Example Code 
Related Methods 
Glossary 



somPrintSelf 



somPrintSelf - Syntax 



This method outputs a brief description that identifies the receiving object. Designed to be overridden. 
Note: For backward compatibility, this method does not take an Environment parameter. 



SOMObject receiver; 

SOMObject rc; 

rc = somPrintSelf (receiver) ; 



somPrintSelf Parameter - receiver 



receiver (SOMObject) 

A pointer to the object to be described. 



somPrintSelf Parameter - rc 



rc (SOMObject) 

Returns a pointer to the receiver object as its result. 



somPrintSelf - Parameters 



receiver (SOMObject) 

A pointer to the object to be described. 

rc (SOMObject) 

Returns a pointer to the receiver object as its result. 



somPrintSelf - Remarks 



somPrintSelf should output a brief string containing key information useful to identify the receiver object, rather than a complete dump of 
the receiver object state as provided by somDumpSelflnt. The somPrintSelf method should use the character output routine 
SOMOutCharRoutine (or any of the somPrintf functions) for this purpose. The default implementation outputs the name of the receiver 
object's class and the receiver's address in memory. 

Because the most specific identifying information for an object will often be found within instance data introduced by the class of an object, it 
is likely that a class implementor that overrides this method will not need to invoke parent methods in order to provide a useful string 
identifying the receiver object. 



somPrintSelf - Original Class 



SOMObject 



somPrintSelf - Related Methods 



Methods 

• somDumpSelf 

• somDumpSelflnt 



somPrintSelf - Example Code 



#include <animal.h> 
main ( ) 

{ 

Animal my Animal; 
my Animal = AnimalNew (); 
/* ... */ 

_somPrintSelf (my Animal) ; 
_somFree (my Animal) ; 

} 

/* 

Output from this program: 




{An instance of class Animal at address 0001CEC0} 
*/ 



somPrintSelf - Topics 



Select an item: 
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Parameters 
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Remarks 
Original Class 
Example Code 
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somResetObj 



somResetObj - Syntax 



Resets an object's class to its true class after use of the somCastObj method. 

SOMObject receiver; 

boolean rc; 

rc = somResetObj (receiver) ; 



somResetObj Parameter - receiver 



receiver (SOMObject) 

A pointer to a SOM object. 



somResetObj Parameter - rc 



rc (boolean) 

The somResetObj method returns 1 (TRUE) always. 



somResetObj - Parameters 



receiver (SOMObject) 

A pointer to a SOM object. 



rc (boolean) 

The somResetObj method returns 1 (TRUE) always. 



somResetObj - Remarks 



The somResetObj method resets an object's class to its true class after use of the somCastObj method. 



somResetObj - Original Class 

SOMObject 



somResetObj - Related Methods 



Methods 



somCastObj 



somResetObj - Example Code 



#include <som.h> 
main ( ) 

{ 

SOMClassMgr cm = somEnvironmentNew ( ) ; 
SOM_Test (1 == _somCastObj (cm, _SOMObject) ) ; 
_somDumpSelf (cm, 0)); 

SOM_Test(l == _somResetObj (cm) ) ; 
_somDumpSelf (cm, 0); 

} 



(null) 

/* output: 

* {An instance of class SOMClassMgr->SOMOb ject 

* at address 20061268 

* } 

* {An instance of class SOMClassMgr at address 20061268 




* ... <SOMClassMgr State Information> . . . 

* } 

*/ 



somResetObj - Topics 



Select an item: 
Syntax 
Parameters 
Returns 
Remarks 
Original Class 
Example Code 
Related Methods 
Glossary 



somRespondsTo 



somRespondsTo - Syntax 



This method tests whether the receiving object supports a given method. Not generally overridden. Note: For backward compatibility, this 
method does not take an Environment parameter. 



SOMObject receiver; 
somld methodld; 
boolean rc; 

rc = somRespondsTo (receiver, methodld); 



somRespondsTo Parameter - receiver 



receiver (SOMObject) 

A pointer to the object to be tested. 



somRespondsTo Parameter - methodld 



methodld (somld) 

A somld that represents the name of the desired method. 



somRespondsTo Parameter - rc 



rc (boolean) 

Returns TRUE if the specified method can be invoked on the receiving object, and FALSE otherwise. 



somRespondsTo - Parameters 



receiver (SOMObject) 

A pointer to the object to be tested. 

methodld (somld) 

A somld that represents the name of the desired method, 
rc (boolean) 

Returns TRUE if the specified method can be invoked on the receiving object, and FALSE otherwise. 



somRespondsTo - Remarks 



The somRespondsTo method tests whether a specific (static or dynamic) method can be invoked on the receiver object. This test 
equivalent to determining whether the class of the receiver supports the specified method on its instances. 



somRespondsTo - Original Class 

SOMObject 



somRespondsTo - Related Methods 

Methods 

• somSupportsMethod 



somRespondsTo - Example Code 




/* 

Note: Animal supports a setSound method; 

Animal does not support a doTrick method. 

*/ 

#include <animal.h> 
main ( ) 

{ 

An ima 1 my An ima 1 ; 

char *methodNamel = "setSound"; 

char *methodName2 = "doTrick"; 

my Animal = AnimalNew(); 

if (_somResponds To (my Animal, SOM_IdFromString (methodNamel ) ) ) 
somPrintf ( "my Animal responds to %s\n", methodNamel); 
if (_somResponds To (my Animal, SOM_IdFromString (methodName2 ) ) ) 
somPrintf ( "my Animal responds to %s\n", methodName2) ; 
_somFree (my Animal) ; 



/* 

Output from this program: 
myAnimal responds to setSound 
*/ 



somRespondsTo - Topics 



Select an item: 
Syntax 
Parameters 
Returns 
Remarks 
Original Class 
Example Code 
Related Methods 
Glossary 



somUninit 



somUninit - Syntax 



This method un-initializes the receiving object. Designed to be overridden by class implementors. Not normally invoked directly by object 
clients. 

Note: For backward compatibility, this method does not take an Environment parameter. 

SOMObject receiver; 



somUninit (receiver) ; 



somUninit Parameter - receiver 



receiver (SOMObject) 

A pointer to the object to be un-initialized. 



somUninit Parameter - rc 



rc 



somUninit - Parameters 



receiver (SOMObject) 

A pointer to the object to be un-initialized. 



rc 



somUninit - Remarks 



The somUninit method performs the inverse of object initialization. Class implementors that introduce instance data that points to allocated 
storage should override somUninit so allocated storage can be freed when an object is freed. 

This method is called automatically by somFree to clean up anything necessary (such as extra storage dynamically allocated to the object) 
before somFree releases the storage allocated to the object itself. 

Code responsible for freeing an object must first know that there will be no further references to this object. Once this is known, this code 
would normally invoke somFree (which calls somUninit). In cases where somRenew was used to create an object instance, however, 
somFree cannot be called (e.g., the storage containing the object may simply be a location on the stack), and in this case, somUninit must 
be called explicitly. 

When overriding this method, always call the parent-class versions of this method after doing your own un-initialization. Furthermore, just as 
with somlnit, because your method may be called multiple times (due to multiple inheritance), you should zero out references to memory 
that is freed, and check for zeros before freeing memory and calling the parent methods. 



somUninit - Original Class 



SOMObject 




somUninit - Related Methods 



Methods 

• somlnit 

• somNew 

• som Renew 



somUninit - Example Code 



Following is the implementation for a class An/ma/ that introduces an attribute sound of type string and overrides somlnit and somUninit, 
along with a main program that creates and then frees an instance of class An/ma/. 

#define Animal_Class_Source 
#include <animal.ih> 

#include <string.h> 

SOM_Scope void SOMLINK somlnit (Animal somSelf) 

{ 

AnimalData *somThis = AnimalGetData (somSelf) ; 

Environment *ev = somGetGlobalEnvironment ( ) ; 

Animal_parents_somInit (somSelf) ; 

if (! get_sound (somSelf , ev) ) { 

set_sound (somSelf , ev, SOMMalloc ( 100 ) ) ; 

strcpy ( get_sound (somSelf , ev) , "Unknown Noise"); 

somPrintf ("New Animal Initialized\n" ) ; 

} 

} 



SOM_Scope void SOMLINK somUninit (Animal somSelf) 

{ 

AnimalData *somThis = AnimalGetData (somSelf) ; 
Environment *ev = somGetGlobalEnvironment () ; 

if ( get_sound (somSelf , ev) ) { 

SOMFree ( get_sound ( somSelf , ev) ; 

set_sound (somSelf , ev, (char*)0); 

somPrintf ("Animal Uninitialized\n" ) ; 
Animal_parents_somUninit (somSelf) ; 



/* main program */ 

#include <animal.h> 
void main ( ) 

{ 

An ima 1 my An ima 1 ; 
my Animal = AnimalNew (); 
_somFree (myAnimal) ; 

} 



/* 

Program output : 

New Animal Initialized 
Animal Uninitialized 
*/ 



somUninit - Topics 
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DSOM Framework Reference 



Notes 



DSOM and CORBA 



Distributed SOM (DSOM) is a framework which supports access to objects in a distributed application. DSOM can be viewed as both: 

• an extension to basic SOM facilities 

• an implementation of the "Object Request Broker" (ORB) technology defined by the Object Management Group (OMG), in the 
Common Object Request Broker Architecture (CORBA) specification and standard, Revision 1 .1 . The CORBA 1.1 specification 
is published by x/Open and the Object Management Group (OMG). 

One of the primary contributions of CORBA is the specification of basic runtime interfaces for writing portable, distributable object-oriented 
applications. SOM and DSOM implement those runtime interfaces, according to the CORBA specification. 

In addition to the published CORBA 1 .1 interfaces, it was necessary for to DSOM introduce several of its own interfaces, in those areas 
where: 



• CORBA 1.1 did not specify the full interface (e.g., ImplementationDef, Principal) 

• CORBA 1.1 did not address the function specified by the interface (e.g., "lifecycle" services for object creation and deletion) 

• the functionality of a CORBA 1.1 interface has been enhanced by DSOM. 

Any such interfaces have been noted on the reference page for each DSOM class . 



A note on method naming conventions 



The SOM Toolkit frameworks (including DSOM) and CORBA have slightly different conventions for naming methods. Methods introduced by 
the SOM Toolkit frameworks use prefixes to indicate the framework to which each method belongs, and use capitalization to separate words 
in the method names (for example, somdFindServer). Methods introduced by CORBA have no prefixes, are all lower case, and use 
underscores to separate words in the method names (such as, impl_is_ready). 

DSOM, more than the other SOM Toolkit frameworks, uses a mix of both conventions. The method and class names introduced by CORBA 
1 .1 are implemented as specified, for application portability. Methods introduced by DSOM to enhance a CORBA-defined class also use the 
CORBA naming style. The SOM Toolkit convention for method naming is used for non-CORBA classes which are introduced by DSOM. 



get_next_response 



get_next_response - Syntax 



This function returns the next Request object to complete, after starting multiple requests in parallel. 



Environment 

Flags 

Request 

ORBStatus 



*env; 

response_f lags; 
*req; 
rc; 



rc = get_next_response (env, response_f lags, 
req) ; 



get_next_response Parameter - env 



env (Environment *) 

A pointer to the Environment structure for the caller. 



get_next_response Parameter - response_flags 



response_flags (Flags) 

A Flags (unsigned long) variable, used to indicate whether the caller wants to wait for the next request to complete (0), or not wait 
(FSESP_NO_WAIT). 



get_next_response Parameter - req 



req (Request *) 

A pointer to a Request object variable. The address of the next Request object which completes is returned in the Request variable. 



get_next_response Parameter - rc 



rc (ORBStatus) 

May return a non-zero ORBStatus value, which indicates a DSOM error code. (DSOM error codes are listed in Appendix A of the 
SOM Too/k/t User's Guide. ) 



get_next_response - Parameters 



env (Environment *) 

A pointer to the Environment structure for the caller. 



response_flags (Flags) 

A Flags (unsigned long) variable, used to indicate whether the caller wants to wait for the next request to complete (0), or not wait 
(RESP_NO_WAIT). 



req (Request *) 

A pointer to a Request object variable. The address of the next Request object which completes is returned in the Request variable. 



rc (ORBStatus) 

May return a non-zero ORBStatus value, which indicates a DSOM error code. (DSOM error codes are listed in Appendix A of the 
SOM Too/k/t User's Guide. ) 



get_next_response - Remarks 



The get_next_response function returns a pointer to the next Request object to complete after starting multiple requests in parallel. This is 
a synchronization function used in conjunction with the send_multiple_requests function. There is no specific order in which requests will 
complete. 

If the response_//ags field is set to 0, this function will not return until the next request completion. If the caller does not want to become 
blocked, the RESP_NO_WAIT flag should be specified. 



get_next_response - Related Information 



Functions 



send_multiple_requests 



Methods 



send 

get_response 

invoke 



get_next_response - Example Code 



See the example for the send_multiple_requests function. 




get_next_response - Topics 
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ORBfree 



ORBfree - Syntax 



Frees the memory of return values and out arguments that was allocated by DSOM on behalf of the caller of a remote method. 



void *ptr; 

ORBfree (ptr) ; 



ORBfree Parameter - ptr 



ptr 

A pointer to memory that has been dynamically allocated by DSOM for a method return value or out argument. 



ORBfree Parameter - rc 



ORBfree - Parameters 



ptr 



A pointer to memory that has been dynamically allocated by DSOM for a method return value or out argument. 



rc 



ORBfree - Remarks 



The ORBfree function is used to free memory for method return values or out arguments which are placed in memory allocated by DSOM 
(versus the calling program) on behalf of the carter of a remote method. For example, strings, arrays, sequence buffers, and "any" values 
are returned in memory which is dynamically-allocated by DSOM. 

By contrast, memory that DSOM allocates on behalf of the receiver of a remote method (such as, for an object-owned in parameter) should 
be freed using the SOM kernel's SOMFree function rather than ORBfree. 

This function is described in section 5.16, "Argument Passing Considerations", and section 5.17, "Return Result Passing Considerations", of 
the CORBA 1.1 specification. 



ORBfree - Related Information 



Functions 



SOMDNoORBfree 
SOMFree (in SOM kernel) 



ORBfree - Example Code 



#include <somd.h> 

#include <myobject.h> /* provided by user */ 

MyObject obj; 

Environment ev; 
string str; 

/* assume myMethod has the following IDL declaration 

* in the MyObject interface: 

~k 

* void myMethod (out string s) ; 

*/ 

_myMethod (ob j , Sev, Sstr) ; 

/* free storage */ 

ORBfree (str) ; 



ORBfree - Topics 
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send_multiple_requests 



send_multiple_requests - Syntax 



This function initiates multiple Requests in parallel. 



Request 

Environment 

long 

Flags 

ORBStatus 



reqs; 

*env; 

count; 

invoke_f lags ; 
rc; 



rc = send_multiple_requests (reqs, env, 
count, invoke_f lags ) ; 



send_multiple_requests Parameter - reqs 



reqs (Request) 

The address of an array of Requests objects which are to be initiated in parallel. 



send_multiple_requests Parameter - env 



env (Environment *) 

A pointer to the Environment structure for the caller. 



send_multiple_requests Parameter - count 



count (long) 

The number of Request objects in reqs. 



send_multiple_requests Parameter - invoke_flags 



invoke_flags (Flags) 

A Flags (unsigned long) value, used to indicate the following options: 



INV_NO_FSESPONSE 

INV_TERM_ON_ERR 



Indicates the caller does not intend to get any results or out parameter values from any of the 
requests. The requests can be treated as if they are oneway operations. 

If one of the requests causes an error, the remaining requests are not sent. 

The above flag values may be "or"-ed together. 



send_multiple_requests Parameter - rc 



rc (ORBStatus) 

May return a non-zero ORBStatus value, which indicates a DSOM error code. (DSOM error codes are listed in Appendix A of the 
SOM Too/k/t User's Guide. ) 



send_multiple_requests - Parameters 



reqs (Request) 

The address of an array of Requests objects which are to be initiated in parallel, 
env (Environment *) 

A pointer to the Environment structure for the caller, 
count (long) 

The number of Request objects in reqs. 

invoke_flags (Flags) 

A Flags (unsigned long) value, used to indicate the following options: 

INV_NO_RESPONSE Indicates the caller does not intend to get any results or out parameter values from any of the 

requests. The requests can be treated as if they are oneway operations. 
INV_TERM_ON_ERR If one of the requests causes an error, the remaining requests are not sent. 

The above flag values may be "or"-ed together. 



rc (ORBStatus) 

May return a non-zero ORBStatus value, which indicates a DSOM error code. (DSOM error codes are listed in Appendix A of the 
SOM Too/k/t User's Guide . ) 



send_multiple_requests - Remarks 




The send_multiple_requests function initiates multiple Requests "in parallel". (The actual degree of parallelism is system dependent.) 
Each Request object is created using the create_request method, defined on SOMDClientProxy. Like the send method, this function 
returns to the caller immediately without waiting for the Requests to finish. The caller waits for the request responses using the 

get_next_response function. 

This function is described in section 6.3, "Deferred Synchronous Routines", of the CORBA 1.1 specification. 



send_multiple_requests - Related Information 



Functions 



get_next_response 



Methods 



send 

get_response 

invoke 



send_multiple_requests - Example Code 



#include <somd.h> 

/* sum a set of values in parallel */ 

int parallel_sum (Environment *ev, int n, SOMDObject *objs) 

{ 

int index, sum = 0; 

Request *next; 

Request *reqs = (Request*) SOMMalloc (n *sizeof (Request) ) ; 
NamedValue * results = (NamedValue* ) 

SOMMalloc (n * sizeof (Namedvalue) ) ; 

for (i=0; i < n; i++) 

(void) _create_request ( (Context *)NULL, "_get_count " , NULL, 
& (result [i] ) , &(reqs[i]), (Flags) 0) ; 

(void) send__multiple_requests (reqs, ev, n, (Flags) 0) ; 

for (i=0, i < n; i++) { 

(void) get_next_response (ev, (Flags) 0, &next) ; 
index = (next - reqs) ; 

sum += *(( int *) results [ index] . argument ._value) ; 



return ( sum) ; 

} 



send_multiple_requests - Topics 
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somdExceptionFree 



somdExceptionFree - Syntax 



Frees the memory held by the exception structure within an Environment structure, regardless of whether the exception was returned by a 
local or a remote method call. 



Environment *env; 

somdExceptionFree (env) ; 



somdExceptionFree Parameter - env 



env (Environment *) 

The Environment structure whose exception information is to be freed. 



somdExceptionFree Parameter - rc 



somdExceptionFree - Parameters 



env (Environment *) 

The Environment structure whose exception information is to be freed. 



rc 



somdExceptionFree - Remarks 



The somdExceptionFree function frees the memory held by the exception structure within an Environment structure, regardless of 
whether the exception was returned by a local or a remote method call. 

When a DSOM client program invokes a remote method and the method returns an exception in the Environment structure, it is the client's 
responsibility to free the exception. This is done by calling either exception_free or somdExceptionFree on the Environment structure in 
which the exception was returned. (The two functions are equivalent. The exception_free function name is #defined in the som.h or som.xh 
file to provide strict CORBA compliance of function names.) There is a similar function, somExceptionFree, available for SOM 
programmers; DSOM programmers, however, can use somdExceptionFree to free all exceptions (regardless of whether they were 
returned from a local or a remote method call). 



somdExceptionFree - Related Information 



Functions 



• somExceptionFree 

• somExceptionID 

• somExceptionValue 

• somSetExceptionException 

• All SOM Kernel Functions 

Data Structures 

• Environment 



somdExceptionFree - Example Code 



X_foo (x, ev, 23); /* make a remote method call */ 

if (ev->ma jor != NO_EXCEPTION) 

{ 



printf("foo exception = 
/* ... handle exception 

somdExceptionFree (ev) ; 



%s\n", somExceptionld (ev) ) ; 

... */ 

/* free exception */ 



somdExceptionFree - Topics 
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SOMD Init 



SOMDJnit - Syntax 



This function initializes DSOM in the calling process. 



Environment *env; 

SOMD_Init (env) ; 



SOMD Init Parameter - env 



env (Environment *) 

A pointer to the Environment structure for the method caller. 



SOMD Init Parameter - rc 



rc 



SOMD Init - Parameters 



env (Environment *) 

A pointer to the Environment structure for the method caller. 



rc 



SOMD Init - Remarks 



Initializes DSOM in the calling process. This function should be called before any other DSOM functions or methods. This function should 
only be invoked (a) at the beginning of a DSOM program (client or server), to initialize the program, or (b) after SOMDJJninit has been 
invoked, to reinitialize the program. If the program has already been initialized with SOMDJnit, then invoking SOMDJnit again has no 
effect. 

An effect of calling SOMDJnit is that the global variables SOMDObjectMgr, SOMD ImpIRepObject, and SOMDORBObject, are 
initialized with pointers to the (single) instances of the SOMDObjectMgr, ImpIRepository, and ORB objects. 

The global variables SOMD ObjectMgr, SOMD ImpIRepObject, and SOMD ORBObject are set implicitly. 

See Chapter 6 on DSOM in the SOM Too/k/t User's Guide. 



SOMDJnit - Example Code 



#include <somd.h> 

Environment ev; 

/* initialize Environment */ 
SOM_InitEnvironment (&ev) ; 

/* initialize DSOM runtime */ 
SOMD_Init (&ev) ; 



/* Free DSOM resources */ 
SOMD_Uninit (&ev) ; 



SOMDJnit - Topics 
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SOMD NoORBfree 



SOMDJMoORBfree - Syntax 



This function specifies to DSOM that the client program will use the SOMFree function to free memory allocated by DSOM, rather than using 
the ORBfree function. 



SOMD_NoORBf ree () ; 



SOMD NoORBfree Parameter - rc 



SOMD NoORBfree - Parameters 



SOMD NoORBfree - Remarks 



The SOMD_NoORBfree function is used in a DSOM client program to specify to DSOM that the client program will use the SOMFree 
function to free memory allocated by DSOM, rather than using the ORBfree function. 

Typically, a DSOM client program will use SOMFree to free memory returned from local method calls and ORBfree to free memory returned 
from remote method calls. The SOMD_NoORBfree function allows programmers to use a single function (SOMFree) to free blocks of 
memory, regardless of whether they were allocated locally or by DSOM in response to a remote method call. 

SOMD_NoORBfree, if used, should be called just after calling SOMDInit in the client program. In response to this call, DSOM will not keep 
track of the memory it allocates for the client. Instead, it will assume that the client program will be responsible for walking all data structures 
returned from remote method calls, calling SOMFree for each block of memory within. 



SOMD NoORBfree - Related Information 



Functions 

• ORBfree 

• SOMFree 



SOMD_NoORBfree - Example Code 




SOMD_Init () ; 

SOMD_NoORBfree () ; 

/* rest of client program */ 



SOMD_NoORBfree - Topics 
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SOMDRegisterCallback 



SOMDRegisterCallback - Syntax 



This function registers a callback function for handling DSOM request events. 

SOMEEMan emanObj; 

EMRegProc *func; 

SOMD_RegisterCallback (emanObj , func) ; 



SOMD RegisterCallback Parameter - emanObj 



emanObj (SOMEEMan) 

A pointer to an instance of SOMEEman, the Event Manager object. 



SOMD RegisterCallback Parameter - func 



func (EMRegProc *) 

A pointer to an event handler function which will be called by EMan whenever a DSOM request arrives. This function must have the 



following prototype (equivalent to the EMRegProc type defined in "eman.h"): 



ftifdef OS 2 

#pragma linkage) func, system) 
#endif 



void SOMLINK func (SOMEEvent event, void *eventData) 
/* On Windows, using the SOMLINK keywork precludes 
* the support of multiple instances. */ 



SOMDRegisterCallback Parameter - rc 



rc 



SOMD RegisterCallback - Parameters 



emanObj (SOMEEMan) 

A pointer to an instance of SOMEEman, the Event Manager object, 
func (EMRegProc *) 

A pointer to an event handler function which will be called by EMan whenever a DSOM request arrives. This function must have the 
following prototype (equivalent to the EMRegProc type defined in "eman.h''): 

ftifdef OS 2 

♦pragma linkage) func, system) 

#endif 



void SOMLINK func (SOMEEvent event, void *eventData) 
/* On Windows, using the SOMLINK keywork precludes 
* the support of multiple instances. */ 



rc 



SOMD RegisterCallback - Remarks 



When writing event-driven applications where there are event sources other than DSOM requests (e.g., user input, mouse clicks, etc.), 
DSOM cannot be given exclusive control of the "main loop," such as when execute_request_loop is called. Instead, the application should 
use the Event Manager (EMan) framework to register and process all application events. 

The SOMD_RegisterCallback function is used to register a user-supplied DSOM event handler function with EMan. The caller need only 
supply an address of the event handler function, and the instance of the EMan object - the details of registration are implemented by 

SOMDRegisterCallback. 

Callback functions should have the SOMLINK keyword explicitly specified, except on Windows. Using an explicit SOMLINK keyword on 
Windows will preclude the ability of an application to support multiple instances. 




Note: The function SOMD_RegisterCallback must be declared with "system linkage” on OS/2. 

See Chapter 12 of the SOM Too/k/t User's Guide for a description of the Event Manager (EMan) framework, for writing event-driven 
applications. 



SOMDRegisterCallback - Example Code 



#include <somd.h> 

#include <eman.h> 

#ifdef OS2 

#pragma linkage (SOMD*RegisterCallback, system) 

#pragma linkage (DSOMEventCallBack, system) 

#endif 

/* On Windows, this example would omit the SOMLINK keyword. */ 

void SOMLINK DSOMEventCallBack (SOMEEvent event, void *eventData) 

{ 

Environment ev; 

SOM_InitEnvironment (&ev) ; 

_execute_request_loop (SOMD_SOMOAOb ject , &ev, SOMD_NO_WAIT) ; 

} 



main ( ) 

{ 



eman = SOMEEmanNew ( ) ; 

SOMD_RegisterCallback (eman, DSOMEventCallBack) ; 
_someProcessEvents (eman, &ev) ; /* main loop */ 



SOMD RegisterCallback - Topics 
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SOMD Uninit 



SOMDJJninit - Syntax 



This function frees system resources allocated for use by DSOM. 



Environment *env; 

SOMD_Uninit (env) ; 



SOMD Uninit Parameter - env 



env (Environment *) 

A pointer to the Environment structure for the method caller. 



SOMD Uninit Parameter - rc 



SOMD Uninit - Parameters 



env (Environment *) 

A pointer to the Environment structure for the method caller. 



rc 



SOMD Uninit - Remarks 



Frees system resources (shared memory segments, semaphores, etc.) allocated to the calling process for use by DSOM. This function 
should be called before a process exits, to ensure system resources are reused. 

No DSOM functions or methods should be called after SOMD_Uninit has been called. After SOMD_Uninit is called, the program can be 
reinitialized by calling SOMDJnit. (SOMDJJninit would then need to be called again before program termination, to uninitialize the 
program.) 

See Chapter 6 on DSOM in the SOM Too/k/t User's Guide . 



SOMDJJninit - Example Code 



#include <somd.h> 



Environment ev; 

/* initialize Environment */ 
SOM_InitEnvironment (&ev) ; 

/* initialize DSOM runtime */ 
SOMD_Init (&ev) ; 

/* Free DSOM resources */ 

SOMD_Uninit (&ev) ; 



SOMD_Uninit - Topics 
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Context delete Macro 



Context_delete Macro - Syntax 



This macro deletes a Context object. 



Context 

Environment 

Flags 

ORBStatus 



ctxob j ; 
*env; 
del_f lag; 
rc; 



rc = Context_delete Macro (ctxob j , env, 
del_flag) ; 



Context_delete Macro Parameter - ctxobj 



ctxobj (Context) 



A pointer to the Context object to be deleted. 



Context delete Macro Parameter - env 



env (Environment *) 

A pointer to the Environment structure for the caller. 



Context_delete Macro Parameter - del_flag 



del_flag (Flags) 

A bitmask (unsigned long). If the flag CTX_DELETE_DESCENDANTS is specified, the macro deletes the specified Context object 
and all of its descendant Context objects. A zero value indicates that the flag is not set. 



Context_delete Macro Parameter - rc 

rc (ORBStatus) 



Context delete Macro - Parameters 



ctxobj (Context) 

A pointer to the Context object to be deleted, 
env (Environment *) 

A pointer to the Environment structure for the caller. 
del_flag (Flags) 

A bitmask (unsigned long). If the flag CTX_DELETE_DESCENDANTS is specified, the macro deletes the specified Context object 
and all of its descendant Context objects. A zero value indicates that the flag is not set. 

rc (ORBStatus) 



Context delete Macro - Remarks 



This macro deletes the specified Context object. This macro maps to the destroy method of the Context class. 




Context_delete Macro - Expansion 



Context_destroy ( ctxobj, env, del_flag ) 



Context delete Macro - Related Information 



Methods 



Context_destroy 



Context_delete Macro - Example Code 



#include <somd.h> 

Environment ev; 

Context ext, newext; 
long rc; 

/* get the process' default Context */ 

rc = _get_default_context (SOMD_ORBOb ject , &ev, &cxt) ; 

/* make newext a child Context of the default Context (ext) */ 
rc = _create_child (ext , &ev, "myContext", &newcxt) ; 

/* assuming no descendent Contexts have been 
* created from newext, we can destroy newext with flags=0 
*/ 

rc = Context_delete (newext , &ev, (Flags) 0); 



Context_delete Macro - Topics 
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Request_delete Macro 



Request_delete Macro - Syntax 



This macro deletes the memory allocated by the ORB for a Request object. 



Request reqobj; 

Environment *env; 

ORBStatus rc; 

rc = Request_delete Macro (reqobj , env); 



Request_delete Macro Parameter - reqobj 



reqobj (Request) 

A pointer to the Request object to be deleted. 



Request_delete Macro Parameter - env 



env (Environment *) 

A pointer to the Environment structure for the caller. 



Request_delete Macro Parameter - rc 

rc (ORBStatus) 



Request_delete Macro - Parameters 



reqobj (Request) 

A pointer to the Request object to be deleted, 
env (Environment *) 

A pointer to the Environment structure for the caller. 



rc (ORBStatus) 



Request_delete Macro - Remarks 



This macro deletes the specified Request object and all associated memory. This macro maps to the destroy method of the Request class. 



Request_delete Macro - Expansion 



Request_destroy ( reqobj, env ) 



Request_delete Macro - Related Information 



Methods 



Request_destroy 



Request_delete Macro - Example Code 



#include <somd.h> 

#include <repostry.h> 

#include <intfacdf.h> 

#include <foo.h> /* provided by user */ 

/* assume following method declaration in interface Foo : 

* long methodLong (in long inLong, inout long inoutLong) ; 

* then the following code sends a request to execute the call: 

* result = methodLong (fooObj, &ev, 100,200); 

* using the DII without waiting for the result. Then, later, 

* waits for and then uses the result. 

*/ 

Environment ev; 

NVList arglist; 
long rc; 

Foo fooObj; 

Request reqObj; 

NamedValue result; 

/* see the Example code for invoke to see how the request 

* is built 
*/ 

/* Create the Request, reqObj */ 

rc = _create_request (fooObj, &ev, (Context *)NULL, "methodLong", 
arglist, &result, &reqObj, (Flags) 0); 

/* Finally, send the request */ 
rc = _send (reqObj , &ev, (Flags) 0); 




/* do some work, i.e. don't wait for the result */ 

/* wait here for the result of the request */ 
rc = _get_response (reqOb j , Sev, (Flags) 0) ; 

/* use the result */ 

if (result->argument ._value == 9600) (...) 

/* throw away the reqObj */ 

Request_delete (reqObj, Sev) ; 



Request_delete Macro - Topics 
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BOA 



File stem: boa 
Base 

SOMObject 

Metaclass 

SOMMSinglelnstance 

Ancestor Class 
SOMObject 

Subclass 

SOMOA 

Description 

The Basic Object Adapter (BOA) defines the basic interfaces that a server process uses to access services of an Object Request Broker like 
DSOM. The BOA defines methods for creating and exporting object references, registering implementations, activating implementations and 
authenticating requests. 

For more information on the Basic Object Adapter, refer to Chapter 9 in the CORBA 1.1 specification. 

Note: DSOM treats the BOA interface as an abstract class, which merely defines basic runtime interfaces (introduced in the CORBA 
specification) but does not implement those interfaces. Thus, there is no point in instantiating a BOA object. If a BOA object is created, any 
methods invoked on it will return a NOJMPLEMENT exception. Instead, the SOM Object Adapter (SOMOA) subclass provides DSOM 
implementations for BOA methods. When a BOA method is invoked on the SOMOA object, the desired behavior will occur. 

New methods 

The following list shows all the BOA methods. 

• changejmplementation 

• create 



• deactivatejmpl 

• deactivate_obj 

• dispose 

• getjd 

• get_principal 

• impl_is_ready 

• obj_is_ready 

• set_exception 

Overridden methods 

There are currently no overridden methods defined for the BOA class. 



changejmplementation 



changejmplementation - Syntax 



This method changes the implementation associated with the referenced object. (Not /mp/ementedj 



BOA receiver; 

Environment *env; 

SOMDObject obj; 

ImplementationDef impl; 

change_implementation (receiver , env, obj, 
impl) ; 



changejmplementation Parameter - receiver 



receiver (BOA) 

A pointer to a BOA (SOMOA) object for the server. 



changejmplementation Parameter - env 



env (Environment *) 

A pointer to the Environment structure for the method caller. 



changejmplementation Parameter - obj 



obj (SOMDObject) 

A pointer to the SOMDObject object which refers to the application object whose implementation is to be changed. 



changejmplementation Parameter - impl 



impl (ImplementationDef) 

A pointer to the ImplementationDef object representing the new implementation of the application object. 



changejmplementation Parameter - rc 



rc 



The SOMOA implementation always returns a NOJMPLEMENT exception, with a minor code of SOMDERROR_Notlmplemented. 



changejmplementation - Parameters 



receiver (BOA) 

A pointer to a BOA (SOMOA) object for the server, 
env (Environment *) 

A pointer to the Environment structure for the method caller, 
obj (SOMDObject) 

A pointer to the SOMDObject object which refers to the application object whose implementation is to be changed, 
impl (ImplementationDef) 

A pointer to the ImplementationDef object representing the new implementation of the application object. 

rc 

The SOMOA implementation always returns a NOJMPLEMENT exception, with a minor code of SOMDERROR_Notlmplemented. 



changejmplementation - Remarks 



The changejmplementation method is defined by the CORBA specification, but has a nu/t /mp/ementat/on in DSOM. This method always 
returns a NOJMPLEMENT exception. 

In CORBA 1 .1 , the changejmplementation method is provided to allow an application to change the implementation definition of an 
object. 

However, in DSOM, the ImplementationDef identifies the server which implements an object. In these terms, changing an object's 
implementation (i.e., server) would result in a change in the object's location. In DSOM, moving objects from one server to another is 
considered an application-specific task, and hence, no default implementation is provided. 

It is possible, however, to change the program which implements an object's server, or change the class library which implements an 




object's class. To modify the program associated with an ImplementationDef, use the updatejmpldef method defined on 
ImpIRepository. To change the implementation of an object's class, replace the corresponding class library with a new (upward-compatible) 
one. 



changejmplementation - Original Class 

BOA 



changejmplementation - Topics 



Select an item: 

Syntax 

Parameters 

Returns 

Remarks 

Original Class 

Glossary 



create 



create - Syntax 



This method creates a "reference" for a local application object which can be exported to remote clients. 



BOA 

Environment 
ReferenceData 
Interf aceDef 
ImplementationDef 
SOMDObject 



receiver; 
*env; 
id; 
intf; 
impl ; 
rc; 



rc = create (receiver, env, id, intf, impl); 



create Parameter - receiver 



receiver (BOA) 

A pointer to a BOA (SOMOA) object for the server. 



create Parameter - env 



env (Environment *) 

A pointer to the Environment structure for the method caller. 



create Parameter - id 



id (ReferenceData) 

A pointer to the ReferenceData structure containing application-specific information describing the target object. 



create Parameter - intf 



intf (InterfaceDef) 

A pointer to the InterfaceDef object which describes the interface of the target object. 



create Parameter - impl 



impl (ImplementationDef) 

A pointer to the ImplementationDef object which describes the application (server) process which implements the target object. 



create Parameter - rc 



rc (SOMDObject) 

Returns a pointer to a SOMDObject which refers to a local application object. 



create - Parameters 



receiver (BOA) 

A pointer to a BOA (SOMOA) object for the server. 



env (Environment *) 




A pointer to the Environment structure for the method caller. 



id (ReferenceData) 

A pointer to the ReferenceData structure containing application-specific information describing the target object, 
intf (InterfaceDef) 

A pointer to the InterfaceDef object which describes the interface of the target object, 
impl (ImplementationDef) 

A pointer to the ImplementationDef object which describes the application (server) process which implements the target object, 
rc (SOMDObject) 

Returns a pointer to a SOMDObject which refers to a local application object. 



create - Remarks 



The create method creates a SOMDObject which is used as a "reference" to a local application object. An object reference is simply an 
object which is used to refer to another target object - one may think of it as an "id", "link", or "handle." Object references are important in 
DSOM in that their values can be externalized (i.e., can be represented in a string form) for transmission between processes, storage in 
files, and so on. In DSOM, the proxy objects in client processes are remote object references. 

File somdtype.idl contains the specification: typedef sequence<octet,1024> ReferenceData. To create an object reference, the caller 
specifies the ImplementationDef of the calling process, the InterfaceDef of the target application object, and up to 1 024 bytes of 
ReferenceData which is used by the application to identify and activate the application object. When subsequent method calls specify the 
object reference as a parameter, the application will use the reference to find and/or activate the referenced object. 

Note that (as specified in CORBA 1.1) each call to create returns a unique object reference, even if the same parameters are used in 
subsequent calls. For each reference, the ReferenceData is stored in the reference data file (and backup file, if any) for the server. 

The SOMOA class introduces a changejd method which allows a server to modify the ReferenceData of one of its references. (The 
changejd method is not in the CORBA 1 .1 specification.) 

Ownership of the returned SOMDObjectis transferred to the caller. 



create - Original Class 



BOA 



create - Related Methods 



Methods 



• changejd 

• create_constant 

• create_SOM_ref 

• dispose 

• getjd 



create - Example Code 




#include <somd.h> 

#include <repostry.h> 

#include <intfacdf.h> 

Environment ev; 

ReferenceData id; 

InterfaceDef intfdef; 

SOMDObject objref; 

string fname; /* a file name to be saved with reference */ 

/* create the id for the reference */ 
id._maximum = id._length = strlen ( fname) +1 ; 
id._buffer = (string) SOMMalloc (strlen (fname) +1) ; 
strcpy (id._buf fer, fname) ; 

/* get the interface def object for interface Foo*/ 
intfdef = _lookup_id (SOM_Interf aceRepository, &ev, "Foo"); 

objref = _create (SOMD_SOMOAOb ject , 

&ev, id, intfdef, SOMD_ImplDefOb ject ) ; 



create - Topics 



Select an item: 
Syntax 
Parameters 
Returns 
Remarks 
Original Class 
Example Code 
Related Methods 
Glossary 



deactivatejmpl 



deactivatejmpl - Syntax 



This method indicates that a server implementation is no longer ready to process requests. 



BOA receiver; 

Environment *env; 

ImplementationDef impl; 



deactivate_impl (receiver, env, impl) ; 



deactivatejmpl Parameter - receiver 



receiver (BOA) 

A pointer to a BOA (SOMOA) object for the server. 



deactivatejmpl Parameter - env 



env (Environment *) 

A pointer to the Environment structure for the method caller. 



deactivatejmpl Parameter - impl 



impl (ImplementationDef) 

A pointer to the ImplementationDef object representing the implementation to be deactivated. 



deactivatejmpl Parameter - rc 



deactivatejmpl - Parameters 



receiver (BOA) 

A pointer to a BOA (SOMOA) object for the server, 
env (Environment *) 

A pointer to the Environment structure for the method caller, 
impl (ImplementationDef) 

A pointer to the ImplementationDef object representing the implementation to be deactivated. 



rc 



deactivatejmpl - Remarks 




The deactivatejmpl method indicates that the implementation is no longer ready to process requests. 



deactivatejmpl - Original Class 

BOA 



deactivatejmpl - Related Methods 

Methods 

• impl_is_ready 

• activate_imple_failed 

• execute_request_loop 

• execute_next_request 



deactivatejmpl - Example Code 



#include <somd.h> 

ORBStatus rc; 

/* server initialization code ... */ 

/* signal DSOM that server is ready */ 

_impl_is_ready (SOMD_SOMOAOb ject , &ev, SOMD_ImplDefOb ject ) ; 
for (rc = 0 ; rc==0 ; ) { 

rc = _execute_next_request (SOMD_SOMOAOb ject , &ev, waitFlag) ; 
/* perform app specific code between messages here, e.g.,*/ 
numMessagesProcessed++; 

} 



/* signal DSOM that server is deactivated */ 

_deactivate_impl (SOMD_SOMOAOb ject , &ev, SOMD_ImplDef Ob ject ) ; 



deactivatejmpl - Topics 



Select an item: 
Syntax 
Parameters 
Returns 
Remarks 
Original Class 
Example Code 
Related Methods 



Glossary 



deactivate_obj 



deactivate_obj - Syntax 



This method indicates that an object server is no longer ready to process requests. (Not tmp/ementec/.J 



BOA receiver; 

Environment *env; 

SOMDObject obj; 

deactivate_ob j (receiver , env, obj); 



deactivate_obj Parameter - receiver 



receiver (BOA) 

A pointer to a BOA (SOMOA) object for the server. 



deactivate_obj Parameter - env 



env (Environment *) 

A pointer to the Environment structure for the method caller. 



deactivate_obj Parameter - obj 



obj (SOMDObject) 

A pointer to a SOMDObject which identifies the object (server) to be deactivated. 



deactivate_obj Parameter - rc 



rc 



deactivate_obj - Parameters 



receiver (BOA) 

A pointer to a BOA (SOMOA) object for the server, 
env (Environment *) 

A pointer to the Environment structure for the method caller, 
obj (SOMDObject) 

A pointer to a SOMDObject which identifies the object (server) to be deactivated. 



rc 



deactivate_obj - Remarks 



The deactivate_obj method is defined by the CORBA specification, but has a nu/t /mp/ementat/on in DSOM . This method always returns a 
NOJMPLEMENT exception. 

CORBA 1.1 distinguishes between servers that implement many objects ("shared"), versus qervers that implement a single object 
("unshared"). The deactivate_obj method is meant to be used by unshared servers, to indicate that the object (i.e., server) is no longer 
ready to process requests. 

DSOM does not distinguish between servers that implement a single object versus servers that implement multiple objects, so this method 
has no implementation. 



deactivate_obj - Original Class 



BOA 



deactivate_obj - Related Methods 



Methods 

• deactivatejmpl 

• impl_is_ready 

• obj_is_ready 



deactivate_obj - Topics 




Select an item: 
Syntax 
Parameters 
Returns 
Remarks 
Original Class 
Related Methods 
Glossary 



dispose 



dispose - Syntax 



This method destroys an object reference. 



BOA receiver; 

Environment *env; 

SOMDObject obj; 

dispose (receiver , env, obj); 



dispose Parameter - receiver 

receiver (BOA) 

A pointer to a BOA object for the server. 



dispose Parameter - env 



env (Environment *) 

A pointer to the Environment structure for the method caller. 



dispose Parameter - obj 



obj (SOMDObject) 



A pointer to the object reference to be destroyed. 



dispose Parameter - rc 



rc 



dispose - Parameters 



receiver (BOA) 

A pointer to a BOA object for the server, 
env (Environment *) 

A pointer to the Environment structure for the method caller, 
obj (SOMDObject) 

A pointer to the object reference to be destroyed. 

rc 



dispose - Remarks 



The dispose method disposes of an object reference. 



dispose - Original Class 



BOA 



dispose - Related Methods 



Methods 

• create 

• create_constant 

• create_SOM_ref 

• get_id 




dispose - Example Code 



#include <somd.h> 

#include <repostry.h> 

#include <intfacdf.h> 

SOMDObject objref; 

ReferenceData id; 

InterfaceDef intfdef; 

objref = 

_create (SOMD_SOMOAOb ject , &ev, id, intfdef, SOMD_ImplDefOb ject ) 
_dispose (SOMD_SOMOAOb ject , &ev, objref); 



dispose - Topics 



Select an item: 
Syntax 
Parameters 
Returns 
Remarks 
Original Class 
Example Code 
Related Methods 
Glossary 



getjd 



getjd - Syntax 



This method returns reference data associated with the referenced object. 



BOA 

Environment 

SOMDObject 

ReferenceData 



receiver; 
*env; 
ob j ; 
rc; 



rc = get_id (receiver , env, obj) ; 



getjd Parameter - receiver 



receiver (BOA) 

A pointer to a BOA (SOMOA) object for the server. 



get_id Parameter - env 



env (Environment *) 

A pointer to the Environment structure for the method caller. 



getjd Parameter - obj 



obj (SOMDObject) 

A pointer to a SOMDObject object for which to return the ReferenceData. 



getjd Parameter - rc 



rc (ReferenceData) 

Returns a ReferenceData structure associated with the referenced object. 



getjd - Parameters 



receiver (BOA) 

A pointer to a BOA (SOMOA) object for the server, 
env (Environment *) 

A pointer to the Environment structure for the method caller, 
obj (SOMDObject) 

A pointer to a SOMDObject object for which to return the ReferenceData. 
rc (ReferenceData) 

Returns a ReferenceData structure associated with the referenced object. 



getjd - Remarks 



The getjd method returns the reference data associated with the referenced object. 




getjd - Original Class 



BOA 



getjd - Related Methods 



Methods 



create 

create_constant 

dispose 



getjd - Example Code 



#include <somd.h> 

#include <repostry.h> 

#include <intfacdf.h> 

SOMDObject objref; 

ReferenceData idl, id2; 

InterfaceDef intfdef; 

objref = 

_create (SOMD_SOMOAOb ject , &ev, idl, intfdef, SOMD_ImplDefOb ject ) 

/* get the ReferenceData from a SOMDObject */ 
id2 = _get_id (SOMD_SOMOAOb ject , &ev, objref); 



getjd - Topics 



Select an item: 
Syntax 
Parameters 
Returns 
Remarks 
Original Class 
Example Code 
Related Methods 
Glossary 



get_principal 



get_principal - Syntax 



This method returns the ID of the principal that issued the request. 



BOA 

Environment 

SOMDObject 

Environment 

Principal 



receiver; 

*env; 

obj; 

* r req_ev; 

rc; 



get_principal (receiver , env, obj, 
req_ev) ; 



get_principal Parameter - receiver 



receiver (BOA) 

A pointer to a BOA (SOMOA) object for the server. 



get_principal Parameter - env 



env (Environment *) 

A pointer to the Environment structure for the method caller. 



get_principal Parameter - obj 



obj (SOMDObject) 

A pointer to the object reference which is the target of the method call 



get_principal Parameter - req_ev 



req_ev (Environment *) 

A pointer to the Environment object passed as input to the request. 



get_principal Parameter - rc 



rc (Principal) 

Returns a pointer to a Principal object which identifies the user and host from which a request originated. 



get_principal - Parameters 



receiver (BOA) 

A pointer to a BOA (SOMOA) object for the server, 
env (Environment *) 

A pointer to the Environment structure for the method caller, 
obj (SOMDObject) 

A pointer to the object reference which is the target of the method call. 
req_ev (Environment *) 

A pointer to the Environment object passed as input to the request, 
rc (Principal) 

Returns a pointer to a Principal object which identifies the user and host from which a request originated. 



get_principal - Remarks 



The get_principal method returns the ID of the principal that issued a request. 



get_principal - Original Class 

BOA 



get_principal - Related Methods 

Classes 

• Principal 



get_principal - Example Code 




#include <somd.h> 



/* assumed context: inside a method implementation */ 
void methodBody (SOMOb ject *somSelf, Environment *ev, ...) 

{ 

Principal p; 

SOMDObject selfRef; 

Environment localev; 

SOMInitEnvironment (&localev) ; 

/* get a reference to myself from the server object */ 
selfRef = 

somdRefFromSOMOb j (SOMD_ServerOb ject , &ev, somSelf ) ; 

/* get principal information from the SOMOA */ 
p = _get_principal (SOMD_SOMOAOb ject , &localev, selfRef, ev); 

printf ( "user = %s, host = %s\n", 

get_userName (p) , get_hostName (p) ) ; 



get_principal - Topics 



Select an item: 
Syntax 
Parameters 
Returns 
Remarks 
Original Class 
Example Code 
Related Methods 
Glossary 



impl_is_ready 



impl_is_ready - Syntax 



This method indicates that the implementation is ready to process requests. 



BOA receiver; 

Environment *env; 

ImplementationDef impl; 

imp l_is_ready (receiver , env, impl); 



impl_is_ready Parameter - receiver 



receiver (BOA) 

A pointer to a BOA (SOMOA) object for the server. 



impl_is_ready Parameter - env 



env (Environment *) 

A pointer to the Environment structure for the method caller. 



impljs_ready Parameter - impl 



impl (ImplementationDef) 

A pointer to the ImplementationDef object indicating which implementation is ready. 



impl_is_ready Parameter - rc 



impl_is_ready - Parameters 



receiver (BOA) 

A pointer to a BOA (SOMOA) object for the server, 
env (Environment *) 

A pointer to the Environment structure for the method caller, 
impl (ImplementationDef) 

A pointer to the ImplementationDef object indicating which implementation is ready. 



rc 




impl_is_ready - Remarks 



The impl_is_ready method Indicates that the implementation is ready to process requests. 



impljs_ready - Original Class 



BOA 



impljs_ready - Related Methods 



Methods 

• deactivate_impl 

• activate_impl_failed 

• obj_is_ready 

• execute_request_loop 

• execute_next_request 



impljs_ready - Example Code 



#include <somd.h> /* needed by all servers */ 

main(int argc, char **argv) 

{ 

Environment ev; 

SOM_InitEnvironment (&ev) ; 

/* Initialize the DSOM run-time environment */ 

SOMD_Init (&ev) ; 

/* Retrieve its ImplementationDef from the Implementation 
Repository by passing its implementation ID as a key */ 
SOMD_ImplDefOb ject = 

_f ind_impldef (SOMD_ImplRepOb ject , &ev, argv[l]); 

/* Tell DSOM that the server is ready to process requests */ 
_impl_is_ready (SOMD_SOMOAOb ject , &ev, SOMD_ImplDef Ob ject ) ; 



impl_is_ready - Topics 



Select an item: 
Syntax 



Parameters 
Returns 
Remarks 
Original Class 
Example Code 
Related Methods 
Glossary 



obj_is_ready 



obj _is_ready - Syntax 



Indicates that an object (server) is ready to process requests. (Not /mp/emented) 



BOA 

Environment 

SOMDObject 

ImplementationDef 



receiver; 
*env; 
ob j ; 
impl; 



obj_is_ready (receiver , env, obj, impl); 



obj _is_ready Parameter - receiver 



receiver (BOA) 

A pointer to a BOA (SOMOA) object for the server. 



obj_is_ready Parameter - env 



env (Environment *) 

A pointer to the Environment structure for the method caller. 



obj _is_ready Parameter - obj 



obj (SOMDObject) 

A pointer to a SOMDObject which identifies the object (server) which is ready. 



obj_is_ready Parameter - impl 



impl (ImplementationDef) 

A pointer to the ImplementationDef object representing the object that is ready. 



obj _is_ready Parameter - rc 



obj_is_ready - Parameters 



receiver (BOA) 

A pointer to a BOA (SOMOA) object for the server, 
env (Environment *) 

A pointer to the Environment structure for the method caller, 
obj (SOMDObject) 

A pointer to a SOMDObject which identifies the object (server) which is ready, 
impl (ImplementationDef) 

A pointer to the ImplementationDef object representing the object that is ready. 



rc 



obj_is_ready - Remarks 



The obj_is_ready method is defined by the CORBA specification, but has a nu// /mp/ementat/on /n DSOM. This method always returns a 
NOJMPLEMENT exception. 

CORBA 1.1 distinguishes between servers that implement many objects ("shared"), versus servers that implement a single object 
("unshared"). The obj_is_ready method is meant to be used by unshared servers, to indicate that the object (i.e., server) is ready to 
process requests. 

DSOM does not distinguish between servers that implement a single object versus servers that implement multiple objects, so this method 
has no implementation. 



obj_is_ready - Original Class 




BOA 



obj_is_ready - Related Methods 



Methods 



impl_is_ready 

deactivate_impl 

deactivate_obj 

activate_impl_failed 



obj_is_ready - Topics 



Select an item: 
Syntax 
Parameters 
Returns 
Remarks 
Original Class 
Related Methods 
Glossary 



set_exception 



set_exception - Syntax 



This method returns an exception to a client. 



BOA 

Environment 
except ion_type 
string 
void 



receiver; 

*env; 

major; 

except_name ; 
*param; 



set_exception (receiver , env, major, except_name, 
param) ; 



set_exception Parameter - receiver 



receiver (BOA) 

A pointer to a BOA (SOMOA) object for the server. 



set_exception Parameter - env 



env (Environment *) 

A pointer to the Environment structure for the method caller. 



set_exception Parameter - major 



major (exception_type) 

One of the exception types NO_EXCEPTION, USER_EXCEPTION, or SYSTEM_EXCEPTION. 



set_exception Parameter - except_name 



except_name (string) 

A string representing the exception type identifier. 



set_exception Parameter - param 



param 

A pointer to the associated data. 



set_exception Parameter - rc 



rc 



set_exception - Parameters 




receiver (BOA) 

A pointer to a BOA (SOMOA) object for the server, 
env (Environment *) 

A pointer to the Environment structure for the method caller, 
major (exception_type) 

One of the exception types NO_EXCEPTION, USER_EXCEPTION, or SYSTEM_EXCEPTION. 

except_name (string) 

A string representing the exception type identifier. 



param 

A pointer to the associated data. 



rc 



set_exception - Remarks 



The set_exception method returns an exception to the client. The major parameter can have one of three possible values: 



NO_EXCEPTION 

USER_EXCEPTION 
SYSTEM EXCEPTION 



Indicates a normal outcome of the operation. It is not necessary to invoke set_exception to indicate 
a normal outcome: it is the default behavior if the method simply returns. 

Indicates a user-defined exception. 

Indicates a system-defined exception. 



set_exception - Original Class 

BOA 



set_exception - Example Code 



#include <somd.h> 

#include <myobject.h> /* provided by user */ 

/* assuming following IDL declarations in the MyObject interface: 

* exception foo; 

* void myMethodO raises (BadCall) ; 

* then within the implementation of myMethod, the 

* following call can raise a BadCall exception: */ 

_set_exception ( SOMD_SOMOAOb ject , 

&ev, USER_EXCEPTION, ex_MyOb ject_BadCall , NULL) ; 




set_exception - Topics 



Select an item: 
Syntax 
Parameters 
Returns 
Remarks 
Original Class 
Example Code 
Glossary 



Context 



File stem: cntxt 
Base 

SOMObject 

Metaclass 

SOMCIass 

Ancestor Classes 
SOMObject 

Description 

The Context class implements the CORBA Context object described in section 6.5 beginning on page 1 16 of CORBA 1 .1 . A Context object 
contains a list of properties, each consisting of a name and a string value associated with that name. Context objects are created/accessed 
by the get_default_context method defined in the ORB object. 

New methods 

The following list shows all the Context methods. 

• create_child 

• delete_values 

• destroy* 

• get_values 

• set_one_value 

• set_values 

(* The destroy method was defined as delete in CORBA 1.1, which conflicts with the delete operator in C++. However, there is a 
Context_delete macro defined for CORBA compatibility.) 

Overridden methods 

The following list shows all the methods overridden by the Context class. These methods are overridden in order to modify the behavior 
defined by an ancestor class. 

• somlnit 



create child 



create_child - Syntax 



This method creates a child of a Context object. 



Context 

Environment 

Identifier 

Context 

ORBStatus 



receiver; 
*env; 
ctx_name ; 
child_ctx; 
rc; 



rc = create_child (receiver , env, ctx_name, 
child_ctx) ; 



create child Parameter - receiver 



receiver (Context) 

A pointer to the Context object for which a child is to be created. 



create child Parameter - env 



env (Environment *) 

A pointer to the Environment structure for the method caller. 



create child Parameter - ctx name 



ctx_name (Identifier) 

The name of the child Context to be created. 



create child Parameter - child ctx 



child_ctx (Context) 

The address where a pointer to the created child Context object is to be stored. 



create child Parameter - rc 



rc (ORBStatus) 

Returns an ORBStatus value representing the return code from the operation. 



create child - Parameters 



receiver (Context) 

A pointer to the Context object for which a child is to be created, 
env (Environment *) 

A pointer to the Environment structure for the method caller. 
ctx_name (Identifier) 

The name of the child Context to be created. 
child_ctx (Context) 

The address where a pointer to the created child Context object is to be stored, 
rc (ORBStatus) 

Returns an ORBStatus value representing the return code from the operation. 



create child - Remarks 



The create_child method creates a child Context object. 

The returned Context object is chained to its parent. That is, searches on the child Context object will look in the parent (and so on, up the 
Contexttree), if necessary, for matching property names. 



create_child - Original Class 



Context 



create_child - Example Code 



#include <somd.h> 

Environment ev; 

Context ext, newext; 
long rc; 

/* get the process' default Context */ 

rc = _get_default_context (SOMD_ORBOb ject , &ev, &cxt) ; 

/* make newext a child Context of the default Context (ext) */ 
rc = _create_child (ext , &ev, "myContext", &newcxt) ; 




create_ 


child - Topics 


Select an item: 
Syntax 
Parameters 
Returns 
Remarks 
Original Class 
Example Code 
Glossary 





delete 


values 



delete_ 


values - Syntax 



This method deletes property value(s). 



Context 

Environment 

Identifier 

ORBStatus 


receiver; 

*env; 

prop_name ; 
rc; 



rc = delete_values (receiver, env, prop_name) ; 

delete_values Parameter - receiver 

receiver (Context) 

A pointer to the Context object from which values will be deleted. 

delete_values Parameter - env 

env (Environment *) 

A pointer to the Environment structure for the method caller. 



delete_values Parameter - prop_name 



prop_name (Identifier) 

An identifier specifying the property value(s) to be deleted. 



delete values Parameter - rc 



rc (ORBStatus) 

Returns an ORBStatus value representing the return code from the operation. 



delete values - Parameters 



receiver (Context) 

A pointer to the Context object from which values will be deleted, 
env (Environment *) 

A pointer to the Environment structure for the method caller. 
prop_name (Identifier) 

An identifier specifying the property value(s) to be deleted, 
rc (ORBStatus) 

Returns an ORBStatus value representing the return code from the operation. 



delete values - Remarks 



The delete_values method deletes the specified property value(s) from a Context object. If prop_name has a trailing wildcard 
character("*"), then all property names that match will be deleted. 

Search scope is always limited to the specified Context object. 

If no matching property is found, an exception is returned. 



delete_values - Original Class 

Context 



delete values - Related Methods 




Methods 



set_one_value 

set_values 

get_values 



delete_values - Example Code 



#include <somd.h> 

Environment ev; 

Context ext, newext; 
long rc; 

/* get the process' default Context */ 

rc = _get_default_context (SOMD_ORBOb ject , &ev, &cxt) ; 

/* make newext a child Context of the default Context (ext) */ 
rc = _create_child (ext , &ev, "myContext", &newcxt) ; 
rc = _set_one_value (newext , &ev, "username", "joe"); 

rc = _delete_values (newext , &ev, "username"); 



delete_values - Topics 



Select an item: 
Syntax 
Parameters 
Returns 
Remarks 
Original Class 
Example Code 
Related Methods 
Glossary 



destroy 



destroy - Syntax 



This method deletes a Context object. 



Context 



receiver; 



Environment 

Flags 

ORBStatus 



env; 

del_f lag; 
rc; 



rc = destroy (receiver, env, del_flag) ; 



destroy Parameter - receiver 



receiver (Context) 

A pointer to the Context object to be deleted. 



destroy Parameter - env 



env (Environment *) 

A pointer to the Environment structure for the method caller. 



destroy Parameter - del_flag 



del_flag (Flags) 

A bitmask (unsigned long). If the option flag CTX_DELETE_DESCENDENTS is specified, the method deletes the indicated Context 
object and all of its descendent Context objects. Or, a zero value indicates the flag is not set. 



destroy Parameter - rc 



rc (ORBStatus) 

Returns an ORBStatus value representing the return code from the operation. 



destroy - Parameters 



receiver (Context) 

A pointer to the Context object to be deleted, 
env (Environment *) 

A pointer to the Environment structure for the method caller. 



del_flag (Flags) 



A bitmask (unsigned long). If the option flag CTX_DELETE_DESCENDENTS is specified, the method deletes the indicated Context 
object and all of its descendent Context objects. Or, a zero value indicates the flag is not set. 

rc (ORBStatus) 

Returns an ORBStatus value representing the return code from the operation. 



destroy - Remarks 



The destroy method deletes the specified Context object. 

Note: This method is called "delete" in the CORBA 1 .1 specification. However, the word "delete" is a reserved operator in C++, so the name 
"destroy"was chosen as an alternative. For CORBA compatibility, a macro defining Context_delete as an alias for destroy has been 
included in the C header files. 



destroy - Original Class 

Context 



destroy - Example Code 



#include <somd.h> 

Environment ev; 

Context ext, newext; 
long rc; 

/* get the process' default Context */ 

rc = _get_default_context (SOMD_ORBOb ject , &ev, &cxt) ; 

/* make newext a child Context of the default Context (ext) */ 
rc = _create_child (ext , &ev, "myContext", &newcxt) ; 

/* assuming no descendent Contexts have been 
* created from newext, we can destroy newext with flags=0 
*/ 

rc = _destroy (newext , &ev, (Flags) 0); 



destroy - Topics 



Select an item: 
Syntax 
Parameters 
Returns 
Remarks 
Original Class 
Example Code 
Glossary 



get_values 



get_values - Syntax 



This method retrieves the specified property values. 



Context 

Environment 

Identifier 

Flags 

Identifier 

NVList 

ORBStatus 



receiver; 

*env; 

start_scope; 
op_f lags; 
prop_name; 
values; 
rc; 



rc = get_values (receiver, env, start_scope, 
op_flags, prop_name, values) ; 



get_values Parameter - receiver 



receiver (Context) 

A pointer to the Context object from which the properties are to be retrieved. 



get_values Parameter - env 



env (Environment *) 

A pointer to the Environment structure for the method caller. 



get_values Parameter - start_scope 



start_scope (Identifier) 

An Identifier specifying the name of the Context object at which search for the properties should commence. 



get_values Parameter - op_flags 



op_flags (Flags) 

This parameter is currently not used (the CTX_RESTRICT_SCOPE flag is currently not supported); callers can simply pass zero, 
object. 



get_values Parameter - prop_name 



prop_name (Identifier) 

An Identifier specifying the name of the property value(s) to return. 



get_values Parameter - values 



values (NVList) 

The address to store a pointer to the resulting NVList object. 



get_values Parameter - rc 



rc (ORBStatus) 

Returns an ORBStatus value representing the return code from the operation. 



get_values - Parameters 



receiver (Context) 

A pointer to the Context object from which the properties are to be retrieved, 
env (Environment *) 

A pointer to the Environment structure for the method caller. 
start_scope (Identifier) 

An Identifier specifying the name of the Context object at which search for the properties should commence. 
op_flags (Flags) 

This parameter is currently not used (the CTX_RESTRICT_SCOPE flag is currently not supported); callers can simply pass zero, 
object. 

prop_name (Identifier) 

An Identifier specifying the name of the property value(s) to return, 
values (NVList) 

The address to store a pointer to the resulting NVList object. 



rc (ORBStatus) 




Returns an ORBStatus value representing the return code from the operation. 



get_values - Remarks 



The get_values method retrieves the specified Context property values(s). If prop_name has a trailing wildcard characterf*”), then all 
matching properties and their values are returned. OWNERSHIP of the returned NVList object is transferred to the caller. 

If no properties are found, an error is returned and no property list is returned. 

Scope indicates the level at which to initiate the search for the specified properties. If a property is not found at the indicated level, the 
search continues up the Context object tree until a match is found or all Context objects in the chain have been exhausted. 

If scope name is omitted, the search begins with the specified Context object. If the specified scope name is not found, an exception is 
returned. 



get_values - Original Class 



Context 



get_values - Related Methods 



Methods 

• set_one_value 

• set_values 

• delete_values 



get_values - Example Code 



#include <somd.h> 



Environment ev; 
Context cxtl, cxt2; 
string *cxtlprops; 
long rc, i, numprops; 
NVList nvp; 



for (i= numprops; i > 0; i — ) { 

/* get the value of the *cxtlprops property from cxtl */ 
rc = _get_values (cxtl , &ev, NULL, (Flags) 0, *cxtlprops, 
/* and if found then update cxt2 with that name-value pair 
if (rc == 0) rc = _set_values (cxt2 , &ev, nvp); 

_free (nvp, &ev) ; 
cxtlprops++; 



&nvp) ; 
*/ 




get_values - Topics 



Select an item: 
Syntax 
Parameters 
Returns 
Remarks 
Original Class 
Example Code 
Related Methods 
Glossary 



set one value 



set_one_value - Syntax 



This method adds a single property to the specified Context object. 



Context 

Environment 

Identifier 

string 

ORBStatus 



receiver; 

*env; 

prop_name; 

value; 

rc; 



rc = set_one_value (receiver, env, prop_name, 
value) ; 



set one value Parameter - receiver 



receiver (Context) 

A pointer to the Context object to which the value is to be added. 



set one value Parameter - env 



env (Environment *) 

A pointer to the Environment structure for the method caller. 



set_one_value Parameter - prop_name 



prop_name (Identifier) 

The name of the property to be added. The prop_name should not end in an asterisk (*). 



set one value Parameter - value 



value (string) 

The value of the property to be added. 



set one value Parameter - rc 



rc (ORBStatus) 

Returns an ORBStatus value representing the return code from the operation. 



set one value - Parameters 



receiver (Context) 

A pointer to the Context object to which the value is to be added, 
env (Environment *) 

A pointer to the Environment structure for the method caller. 
prop_name (Identifier) 

The name of the property to be added. The prop_name should not end in an asterisk (*). 
value (string) 

The value of the property to be added, 
rc (ORBStatus) 

Returns an ORBStatus value representing the return code from the operation. 



set one value - Remarks 



The set_one_value method adds a single property to the specified Context object. 




set_one_value - Original Class 



Context 



set one value - Related Methods 



Methods 



set_values 

get_values 

delete_values 



set_one_value - Example Code 



#include <somd.h> 

Environment ev; 

Context ext, newext; 
long rc; 

/* get the process' default Context */ 

rc = _get_default_context (SOMD_ORBOb ject , &ev, &cxt) ; 

/* make newext a child Context of the default Context (ext) */ 
rc = _create_child (ext , &ev, "myContext", &newcxt) ; 
rc = _set_one_value (newext, &ev, "username", "joe"); 



set_one_value - Topics 



Select an item: 
Syntax 
Parameters 
Returns 
Remarks 
Original Class 
Example Code 
Related Methods 
Glossary 



set values 



set_values - Syntax 



This method adds/changes one or more property values in the specified Context object. 



Context 

Environment 

NVList 

ORBStatus 



receiver; 

*env; 

values; 

rc; 



rc = set_values (receiver, env, values) ; 



set values Parameter - receiver 



receiver (Context) 

A pointer to the Context object for which the properties are to be set. 



set values Parameter - env 



env (Environment *) 

A pointer to the Environment structure for the method caller. 



set values Parameter - values 



values (NVList) 

A pointer to an NVList object containing the properties to be set. 



set values Parameter - rc 



rc (ORBStatus) 

Returns an ORBStatus value representing the return code from the operation. 



set values - Parameters 



receiver (Context) 

A pointer to the Context object for which the properties are to be set. 
env (Environment *) 

A pointer to the Environment structure for the method caller, 
values (NVList) 

A pointer to an NVList object containing the properties to be set. 
rc (ORBStatus) 

Returns an ORBStatus value representing the return code from the operation. 



set values - Remarks 



The set_values method sets one or more property values in the specified Context object. In the NVList, the flags field must be set to zero 
and the TypeCode field associated with an attribute value must be TC_string. 



set_values - Original Class 

Context 



set values - Related Methods 



Methods 



set_one_value 

get_values 

delete_values 



set_values - Example Code 



#include <somd.h> 

Environment ev; 

Context cxtl, cxt2; 
string *cxtlprops; 
long rc, i, numprops; 

NVList nvp; 

for (i= numprops; i > 0; i — ) { 

/* get the value of the *cxtlprops property from cxtl */ 
rc = _get_values (cxtl , &ev, NULL, (Flags) 0, *cxtlprops, &nvp) ; 
/* and if found then update cxt2 with that name-value pair */ 
if (rc — 0) rc = _set_values (cxt2 , &ev, nvp); 

_free (nvp, &ev) ; 
cxtlprops++; 




set_values - Topics 



Select an item: 
Syntax 
Parameters 
Returns 
Remarks 
Original Class 
Example Code 
Related Methods 
Glossary 



ImplementationDef 



File stem: impldef 
Base 

SOMObject 

Metaclass 

SOMCIass 

Ancestor Classes 
SOMObject 

Description 

The ImplementationDef class defines attributes necessary for the DSOM daemon to find and activate the implementation of an object. 

Note: * Details of the ImplementationDef object are not currently defined in the CORBA 1 .1 specification; the attributes which have been 
defined are required by DSOM. 

Attributes 

Listed below is each available attribute, with its corresponding type in parentheses, followed by a description of its purpose: 
impljd (string) 

Contains the DSOM-generated identifier for a server implementation. 
impl_alias (string) 

Contains the "alias" (user-friendly name) for a server implementation. 
impLprogram (string) 

Contains the name of the program or command file which will be executed when a process for this server is started automatically 
by somdd. If the full pathname is not specified, the directories specified in the PATH environment variable will be searched for 
the named program or command file. 

Optionally, the server program can be run under control of a "shell" or debugger, by specifying the shell or debugger name first, 
followed by the name of the server program. (A space separates the two program names.) For example, 

dbx my server 



Servers that are started automatically by somdd will always be passed their impljd as the first parameter. 



impljlags (Flags) 

Contains a bit-vector of flags used to identify server options. Currently, the IMPLDEF_MULTI_TFIREAD flag indicates that each 
request should be executed on a separate thread. IMPLDEF_DISABLE_SVR indicates that the server process has been 
disabled from starting. IMPLDEF_NONSTOPPABLE indicates that the server cannot be shutdown by using the dsom stop or 
dsom restart commands (see "The 'dsom' server manager utility" in Chapter 6 of the SOMobjects Users Guide) or by using the 
corresponding methods of the SOMDServerMgr class (somdShutdownServer and somdRestartServer). 
IMPLDEF_IMPLID_SET indicates that the impljd attribute has already been set when the ImplementationDef object is passed 
to the lmplRepository::add_impldef method. The lmplRepository::add_impldef method normally generates the impljd 
attribute before storing the ImplementationDef object in the Implementation Repository. 

impl_server_class (string) 

Contains the name of the SOMDServer class or subclass created by the server process. 
impl_refdatajile (string) 

Contains the full pathname of the file used to store ReferenceData for the server. 
impl_refdata_bkup (string) 

Contains the full pathname of the backup mirror file used to store ReferenceData for the server, 
impljiostname (string) 

Contains the hostname of the machine where the server is located. 



Note: 

Currently, when stored in the Implementation Repository, file names used in ImplementationDefs are limited to 255 bytes. Implementations 
aliases used in ImplementationDefs are limited to 50 bytes. Class names used in ImplementationDefs are limited to 50 bytes. Flostnames 
are limited to 32 bytes. 

New methods 

There are currently no new methods defined for the ImplementationDef class. 

Overridden methods 

There are currently no overridden methods defined for the ImplementationDef class. 



ImpIRepository 



File stem: implrep 
Base 

SOMObject 

Metaclass 

SOMMSinglelnstance 

Ancestor Classes 
SOMObject 

Description 

The ImpIRepository class defines operations necessary to query and update the DSOM Implementation Repository. 

Note: * The Implementation Repository is described in concept in the CORBA 1.1 specification, but no standard interfaces have been 
defined. These interfaces have all been introduced by DSOM. In addition to using the following interfaces, the DSOM Implementation 
Repository can be queried and updated using the regimpl tool. 

New methods 

The following list shows all the ImpIRepository methods. 

• add_classJo_impldef 

• addjmpldef 

• deletejmpldef 

• find_alljmpldefs 




• find_classes_by_impldef 

■ findjmpldef 

• find_impldef_by_alias 

• find_impldef_by_class 

• remove_class_from_all 

• remove_class_from_impldef 

• updatejmpldef 

Overridden methods 

The following list shows all the methods overridden by the ImpIRepository class. These methods are overridden in order to modify the 
behavior defined by an ancestor class. 

■ somlnit 

• somUninit 



add_class_to_impldef 



add_class_to_impldef - Syntax 



This method associates a class with a server. 



ImpIRepository 

Environment 

Implld 

string 



receiver; 

*env; 

implid; 

classname; 



add_class_to_impldef (receiver, env, 
implid, classname) ; 



add_class_to_impldef Parameter - receiver 



receiver (ImpIRepository) 

A pointer to the ImpIRepository object. 



add_class_to_impldef Parameter - env 



env (Environment *) 

A pointer to the Environment structure for the method caller. 



add_class_to_impldef Parameter - implid 



implid (Implid) 

The Implid identifier for the ImplementationDef of the desired server. 



add_class_to_impldef Parameter - classname 



classname (string) 

A string identifying the class name. 



add_class_to_impldef Parameter - rc 



rc 

An exception is returned if there was an error updating the Implementation Repository. 



add_class_to_impldef - Parameters 



receiver (ImpIRepository) 

A pointer to the ImpIRepository object. 

env (Environment *) 

A pointer to the Environment structure for the method caller, 
implid (Implid) 

The Implid identifier for the ImplementationDef of the desired server. 

classname (string) 

A string identifying the class name. 

rc 

An exception is returned if there was an error updating the Implementation Repository. 



add_class_to_impldef - Remarks 



Associates a class, identified by name, with a server, identified by its Implid. This type of association is used to lookup server 
implementations via the find_impldef_by_class method. 



add_class_to_impldef - Original Class 




ImpIRepository 



add_class_to_impldef - Example Code 



#include <somd.h> 

Environment ev; 

SOMDServer server; 

ImplementationDef impldef; 

Implld implid; 

server = _somdFindServerByName (SOMD_Ob jectMgr , &ev, "stackServer") 
impldef = _get_implementation (server, &ev) ; 
implid = get_impl_id(impldef,&ev); 

_add_class_to_impldef (SOMD_ImplRepOb ject, &ev, implid , "Queue") ; 



add_class_to_impldef - Topics 



Select an item: 
Syntax 
Parameters 
Returns 
Remarks 
Original Class 
Example Code 
Glossary 



addjmpldef 



addjmpldef - Syntax 



This method adds an implementation definition to the Implementation Repository. 



ImpIRepository 

Environment 

ImplementationDef 



receiver; 

*env; 

impldef; 



add_impldef (receiver, env, impldef) ; 



addjmpldef Parameter - receiver 



receiver (ImpIRepository) 

A pointer to the ImpIRepository object. 



addjmpldef Parameter - env 



env (Environment *) 

A pointer to the Environment structure for the method caller. 



addjmpldef Parameter - impldef 



impldef (ImplementationDef) 

A pointer to the ImplementationDef object to add to the Implementation Repository. 



addjmpldef Parameter - rc 



rc 

An exception is returned if there was an error updating the Implementation Repository. 



addjmpldef - Parameters 



receiver (ImpIRepository) 

A pointer to the ImpIRepository object. 

env (Environment *) 

A pointer to the Environment structure for the method caller, 
impldef (ImplementationDef) 

A pointer to the ImplementationDef object to add to the Implementation Repository. 

rc 

An exception is returned if there was an error updating the Implementation Repository. 



addjmpldef - Remarks 




Adds the specified ImplementationDef object to the Implementation Repository. 

Note: Unless the impl_flags attribute of the given ImplementationDef object contains the IMPLDEF_IMPLID_SET flag, the impljd 
attribute of the ImplementationDef object is ignored, and a new impljd value is created for the newly added ImplementationDef object. 



addjmpldef - Original Class 



ImpIRepository 



addjmpldef - Example Code 



#include _somd.h> 

Environment ev; 

ImplementationDef impldef; 

impldef = ImplementationDefNew ( ) ; 

set_impl_program ( impldef , &ev, " /u/ servers / my server " ) ; 

/* set more of the impldef' s attributes here */ 

_add_impldef (SOMD_ImplRepOb ject , &ev, impldef) ; 



addjmpldef - Topics 



Select an item: 
Syntax 
Parameters 
Returns 
Remarks 
Original Class 
Example Code 
Glossary 



deletejmpldef 



deletejmpldef - Syntax 



This method deletes an implementation definition from the Implementation Repository. 



ImplRepository receiver; 

Environment *env; 

Implld implid; 

delete_impldef (receiver, env, implid) ; 



deletejmpldef Parameter - receiver 



receiver (ImplRepository) 

A pointer to the ImplRepository object. 



deletejmpldef Parameter - env 



env (Environment *) 

A pointer to the Environment structure for the method caller. 



deletejmpldef Parameter - implid 



implid (Implld) 

The Implld that identifies the server implementation of interest. 



deletejmpldef Parameter - rc 



rc 

An exception is returned if there was an error updating the Implementation Repository. 



deletejmpldef - Parameters 



receiver (ImplRepository) 

A pointer to the ImplRepository object. 

env (Environment *) 

A pointer to the Environment structure for the method caller. 



implid (Implld) 

The Implld that identifies the server implementation of interest. 

rc 

An exception is returned if there was an error updating the Implementation Repository. 

deletejmpldef - Remarks 

Deletes the specified ImplementationDef object from the Implementation Repository. 



delete_ 


impldef - Original Class 


ImpIRepository 





delete_ 


impldef - Example Code 



#include <somd.h> 

Environment ev; 

ImplementationDef impldef; 

impldef = 

_f ind_impldef_by_name (SOMD_ImplRepOb ject , &ev, "stackServer") ; 
_delete_impldef (SOMD_ImplRepOb ject , &ev, get_impl _id (impldef, &ev) ) 



delete_ 


impldef - Topics 


Select an item: 
Syntax 
Parameters 
Returns 
Remarks 
Original Class 
Example Code 
Glossary 





find_alljmpldefs 



find_alljmpldefs - Syntax 



This method returns all the implementation definitions in the Implementation Repository. 



ImplRepository receiver; 

Environment *env; 

sequence<ImplementationDef s> outimpldef s ; 

ORBStatus rc; 

rc = f ind_all_impldef s (receiver, env, 
outimpldefs) ; 



find_alljmpldefs Parameter - receiver 



receiver (ImplRepository) 

A pointer to an object of class ImplRepository. 



find_alljmpldefs Parameter - env 



env (Environment *) 

A pointer to the Environment structure for the calling method. 



find_alljmipldefs Parameter - outimpldefs 



outimpldefs (sequence<lmplementationDefs>) 

A sequence of ImplementationDefs is returned. 



find_alljmpldefs Parameter - rc 



rc (ORBStatus) 

A zero is returned to indicate success; otherwise, a DSOM error code is returned. 



find_alljmipldefs - Parameters 



receiver (ImpIRepository) 

A pointer to an object of class ImpIRepository. 

env (Environment *) 

A pointer to the Environment structure for the calling method. 



outimpldefs (sequence<lmplementationDefs>) 

A sequence of ImplementationDefs is returned. 



rc (ORBStatus) 

A zero is returned to indicate success; otherwise, a DSOM error code is returned. 



find_alljmpldefs - Remarks 



The find_all_impldefs method searches the Implementation Repository and returns all the ImplementationDef objects in it. 



find_alljmpldefs - Original Class 

ImpIRepository 



find_alljmpldefs - Example Code 

#include <somd.h> 

Environment ev; 

sequence (ImplementationDef) impldefs; 



f ind_all_impldef s (SOMD_ImplRepOb ject , &ev, &impldefs) ; 



find_alljmpldefs - Topics 



Select an item: 
Syntax 
Parameters 
Returns 
Remarks 
Original Class 
Example Code 
Glossary 



find_classes_by_impldef 



find_classes_by_impldef - Syntax 



This method returns a sequence of class names associated with a server. 



ImplRepository receiver; 

Environment *env; 

Implld implid; 

sequence<string> rc; 

rc = f ind_classes_by_impldef (receiver, 
env, implid) ; 



find_classes_by_impldef Parameter - receiver 



receiver (ImplRepository) 

A pointer to the ImplRepository object. 



find_classes_by_impldef Parameter - env 



env (Environment *) 

A pointer to the Environment structure for the method caller. 



find_classes_by_impldef Parameter - implid 



implid (Implld) 

The Implld that identifies the server implementation of interest. 



find_classes_by_impldef Parameter - rc 



rc (sequence<string>) 

A sequence of strings is returned. Ownership of the sequence structure, the string array buffer, and the strings themselves is 
transferred to the caller. 

An exception is returned if there was an error reading the Implementation Repository. 



find_classes_by_impldef - Parameters 



receiver (ImpIRepository) 

A pointer to the ImpIRepository object. 

env (Environment *) 

A pointer to the Environment structure for the method caller, 
implid (Implld) 

The Implld that identifies the server implementation of interest, 
rc (sequence<string>) 

A sequence of strings is returned. Ownership of the sequence structure, the string array buffer, and the strings themselves is 
transferred to the caller. 

An exception is returned if there was an error reading the Implementation Repository. 



find_classes_by_impldef - Remarks 



Searches the class index and returns the sequence of class names supported by a server with the specified imp/ic/. 



find_classes_by_impldef - Original Class 



ImpIRepository 



find_classes_by_impldef - Example Code 



#include <somd.h> 

Environment ev; 

SOMDServer server; 

ImplementationDef impldef; 

Implld implid; 

sequence (string) classes; 

server = _f ind_server_by_name (SOMD_Ob jectMgr , &ev, "stackServer") ; 
impldef = _get_implementation (server, &ev) ; 
implid = get_impl_id (impldef , &ev) ; 

classes = _f ind_classes_by_impldef (SOMD_ImplRepOb ject , &ev, implid) ; 




find_classes_by_impldef - Topics 



Select an item: 
Syntax 
Parameters 
Returns 
Remarks 
Original Class 
Example Code 
Glossary 



findjmpldef 



findjmpldef - Syntax 



This method returns a server implementation definition given its ID. 



ImplRepository 

Environment 

Implld 

ImplementationDef 



receiver; 

*env; 

implid; 

rc; 



rc = find_impldef (receiver, env, implid) ; 



findjmpldef Parameter - receiver 



receiver (ImplRepository) 

A pointer to the ImplRepository object. 



findjmpldef Parameter - env 



env (Environment *) 

A pointer to the Environment structure for the method caller. 



findjmpldef Parameter - implid 



implid (Implld) 

The Implld of the desired ImplementationDef. 



findjmpldef Parameter - rc 



rc (ImplementationDef) 

A copy of the desired ImplementationDef object is returned. Ownership of the object is transferred to the caller. 
An exception is returned if there was an error reading the Implementation Repository. 



findjmpldef - Parameters 



receiver (ImpIRepository) 

A pointer to the ImpIRepository object. 

env (Environment *) 

A pointer to the Environment structure for the method caller, 
implid (Implld) 

The Implld of the desired ImplementationDef. 

rc (ImplementationDef) 

A copy of the desired ImplementationDef object is returned. Ownership of the object is transferred to the caller. 
An exception is returned if there was an error reading the Implementation Repository. 



findjmpldef - Remarks 



Finds and returns the ImplementationDef object whose ID is imp/id. 



findjmpldef - Original Class 

ImpIRepository 



findjmpldef - Example Code 




#include <somd.h> 



main(int argc, char **argv) 

{ 

Environment ev; 

SOM_InitEnvironment (&ev) ; 

/* Initialize the DSOM run-time environment */ 

SOMD_Init ( &ev) ; 

/* Retrieve its ImplementationDef from the Implementation 
Repository by passing its implementation ID as a key */ 
SOMD_ImplDefOb ject = 

_f ind_impldef ( SOMD_ImplRepOb ject , &ev, argv[l] ) ; 

/* Tell DSOM that the server is ready to process requests */ 
_impl_is_ready (SOMD_SOMOAOb ject , &ev, SOMD_ImplDefOb ject ) ; 



findjmpldef - Topics 



Select an item: 
Syntax 
Parameters 
Returns 
Remarks 
Original Class 
Example Code 
Glossary 



find_impldef_by_alias 



find_impldef_by_alias - Syntax 



This method returns a server implementation definition given its user-friendly alias. 



ImplRepository 

Environment 

string 

ImplementationDef 



receiver; 

*env; 

alias_name ; 
rc; 



rc = f ind_impldef_by_alias (receiver, 
env, alias_name) ; 



find_impldef_by_alias Parameter - receiver 



receiver (ImpIRepository) 

A pointer to the ImpIRepository object. 



findjmpldef_by_alias Parameter - env 



env (Environment *) 

A pointer to the Environment structure for the method caller. 



find_impldef_by_alias Parameter - alias_name 



alias_name (string) 

User-friendly name used to identify the implementation. 



find_impldef_by_alias Parameter - rc 



rc (ImplementationDef) 

A copy of the desired ImplementationDef object is returned. Ownership of the object is transferred to the caller. 
An exception is returned if there was an error reading the Implementation Repository. 



find_impldef_by_alias - Parameters 



receiver (ImpIRepository) 

A pointer to the ImpIRepository object. 

env (Environment *) 

A pointer to the Environment structure for the method caller. 
alias_name (string) 

User-friendly name used to identify the implementation, 
rc (ImplementationDef) 

A copy of the desired ImplementationDef object is returned. Ownership of the object is transferred to the caller. 
An exception is returned if there was an error reading the Implementation Repository. 



find_impldef_by_alias - Remarks 




Finds and returns the ImplementationDef object whose alias is a//as_name. 



findjmpldef_by_alias - Original Class 



ImpIRepository 



find_impldef_by_alias - Example Code 



#include <somd.h> 

Environment ev; 

ImplementationDef impldef; 

impldef = 

_f ind_impldef_by_alias (SOMD_ImplRepOb ject , &ev, "stack Server") ; 
_delete_impldef (SOMD_ImplRepOb ject , &ev, get_impl_id (impl def, &ev) ) ; 



find_impldef_by_alias - Topics 



Select an item: 
Syntax 
Parameters 
Returns 
Remarks 
Original Class 
Example Code 
Glossary 



find_impldef_by_class 



find_impldef_by_class - Syntax 



This method returns a sequence of implementation definitions for servers that are associated with a specified class. 



ImpIRepository 

Environment 

string 



receiver; 

env; 

classname; 



sequence< Implement at ionDef > 



rc; 



rc = f ind_impldef_by_class (receiver, 
env, classname) ; 



findjmpldef_by_class Parameter - receiver 



receiver (ImpIRepository) 

A pointer to the ImpIRepository object. 



find_impldef_by_class Parameter - env 



env (Environment *) 

A pointer to the Environment structure for the method caller. 



find_impldef_by_class Parameter - classname 



classname (string) 

A string whose value is the class name of interest. 



find_impldef_by_class Parameter - rc 



rc (sequence<lmplementationDef>) 

Copiess of all ImplementationDef objects are returned in a sequence. Ownership of the sequence structure, the object array buffer, 
and the objects themselves is transfered to the caller. 

An exception is returned if there was an error reading the Implementation Repository. 



find_impldef_by_class - Parameters 



receiver (ImpIRepository) 

A pointer to the ImpIRepository object. 

env (Environment *) 

A pointer to the Environment structure for the method caller. 



classname (string) 

A string whose value is the class name of interest. 



rc (sequence<lmplementationDef>) 

Copiess of all ImplementationDef objects are returned in a sequence. Ownership of the sequence structure, the object array buffer, 
and the objects themselves is transfered to the caller. 



An exception is returned if there was an error reading the Implementation Repository. 



find_impldef_by_class - Remarks 



Returns a sequence of ImplementationDefs for those servers that have registered an association with a specified class. Typically, a server 
will be associated with the classes it knows how to implement by registering its known classes via the add_class_to_impldef method. 



find_impldef_by_class - Original Class 

ImpIRepository 



find_impldef_by_class - Example Code 

#include <somd.h> 

Environment ev; 

sequence (ImplementationDef) impldefs; 
impldef = 

_f ind_impldef_by_class (SOMD_ImplRepOb ject , &ev, "Stack") ; 



find_impldef_by_class - Topics 



Select an item: 
Syntax 
Parameters 
Returns 
Remarks 
Original Class 
Example Code 
Glossary 



remove class from all 



remove_class_from_all - Syntax 



This method removes the association of a particular class from all servers. 



ImplRepository receiver; 

Environment *env; 

string className; 

r emove_c las s_f r om_a 1 1 (receiver, env, 
className) ; 



remove class from all Parameter - receiver 



receiver (ImplRepository) 

A pointer to an object of class ImplRepository. 



remove class from all Parameter - env 



env (Environment *) 

A pointer to the Environment structure for the calling method. 



remove class from all Parameter - className 



className (string) 

A string whose value is the class name of interest. 



remove class from all Parameter - rc 



rc 



remove class from all - Parameters 



receiver (ImpIRepository) 

A pointer to an object of class ImpIRepository. 

env (Environment *) 

A pointer to the Environment structure for the calling method. 
className (string) 

A string whose value is the class name of interest. 



rc 



remove class from all - Remarks 



The remove_class_from_all method removes the c/assName from all of the ImplementationDefs. 



remove_class_from_all - Original Class 

ImpIRepository 



remove_class_from_all - Example Code 



#include <somd.h> 

Environment ev; 

remove_class_f rom_all (SOMD_ImplRepOb ject , &ev, "Stack"); 



remove_class_from_all - Topics 



Select an item: 
Syntax 
Parameters 
Returns 
Remarks 
Original Class 
Example Code 
Glossary 



remove_class_fromJmpldef 



remove_class_fromJmpldef - Syntax 



This method removes the association of a particular class with a server. 



ImplRepository 

Environment 

Implld 

string 



receiver; 
*env; 
implid; 
classname ; 



remove_class_f rom_impldef (receiver, 
env, implid, classname) ; 



remove_class_from_impldef Parameter - receiver 



receiver (ImplRepository) 

A pointer to the ImplRepository object. 



remove_class_from_impldef Parameter - env 



env (Environment *) 

A pointer to the Environment structure for the method caller. 



remove_class_fromJmpldef Parameter - implid 



implid (Implld) 

A pointer to an ImplRepository object. 



remove_class_from_impldef Parameter - classname 



classname (string) 

A string whose value is the class name of interest. 



remove_class_from_impldef Parameter - rc 



rc 

An exception is returned if there was an error updating the Implementation Repository. 



remove_class_fromJmpldef - Parameters 



receiver (ImpIRepository) 

A pointer to the ImpIRepository object. 

env (Environment *) 

A pointer to the Environment structure for the method caller, 
implid (Implld) 

A pointer to an ImpIRepository object, 
classname (string) 

A string whose value is the class name of interest. 



rc 

An exception is returned if there was an error updating the Implementation Repository. 



remove_class_from_impldef - Remarks 



Removes the specified class name from the set of class names associated with the server implementation identified by imp/id 



remove_class_from_impldef - Original Class 



ImpIRepository 



remove_class_from_impldef - Example Code 



#include <somd.h> 

Environment ev; 

SOMDServer server; 

ImplementationDef impldef; 

Implld implid; 

server = _f ind_server_by_name (SOMD_Ob jectMgr , &ev, "stackServer") ; 
impldef = _get_implementation (server, &ev) ; 




implid = get_impl_id (impldef , &ev) ; 

_remove_c 1 a s s_f r om_imp 1 de f ( S OMD_Imp 1 RepOb j e c t , 

&ev, implid, "Queue" ) ; 



remove_classJromJmpldef - Topics 



Select an item: 
Syntax 
Parameters 
Returns 
Remarks 
Original Class 
Example Code 
Glossary 



updatejmpldef 



updatejmpldef - Syntax 



This method updates an implementation definition in the Implementation Repository. 



ImplRepository receiver; 

Environment *env; 

ImplementationDef impldef; 

update_impldef (receiver, env, impldef) ; 



updatejmpldef Parameter - receiver 



receiver (ImplRepository) 

A pointer to the ImplRepository object. 



updatejmpldef Parameter - env 



env (Environment *) 

A pointer to the Environment structure for the method caller. 



updatejmpldef Parameter - impldef 



impldef (ImplementationDef) 

A pointer to an ImplementationDef object, whose values are to be saved in the Implementation Repository. 



updatejmpldef Parameter - rc 



rc 

An exception is returned if there was an error updating the Implementation Repository. 



updatejmpldef - Parameters 



receiver (ImpIRepository) 

A pointer to the ImpIRepository object. 

env (Environment *) 

A pointer to the Environment structure for the method caller, 
impldef (ImplementationDef) 

A pointer to an ImplementationDef object, whose values are to be saved in the Implementation Repository. 

rc 

An exception is returned if there was an error updating the Implementation Repository. 



updatejmpldef - Remarks 



Replaces the state of the specified ImplementationDef object in the Implementation Repository. The ID of the /mp/def determines which 
object gets updated in the Implementation Repository. 



updatejmpldef - Original Class 



ImpIRepository 



updatejmpldef - Example Code 




#include _somd.h> 

Environment ev; 

SOMDObject objref; 

ImplementationDef impldef; 

impldef = _get_implementation (objref , &ev) ; 

set_impl_program ( impldef, &ev, " /u/ joe /bin /my server" ) ; 

_update_impldef (SOMD_ImplRepOb ject , &ev, impldef) ; 



update Jmpldef - Topics 



Select an item: 
Syntax 
Parameters 
Returns 
Remarks 
Original Class 
Example Code 
Glossary 



NVList 



File stem: nvlist 
Base 

SOMObject 

Metaclass 

SOMCIass 

Ancestor Classes 
SOMObject 

Description 

The type NamedValue is a standard datatype defined in CORBA (see the CORBA 1.1 page 1 06). It can be used either as a parameter type 
or as a mechanism for describing arguments to a request. The NVList class implements the NVList object used for constructing lists 
composed of NamedValues. NVLists can be used to describe arguments passed to request operations or to pass lists of property names 
and values to context object routines. Addition information about NVList is contained in Chapter 6 of the CORBA 1.1 specification. 

New methods 

The following list shows all the NVList methods. 

• addjtem 

• free 

• free_memory 

• get_count 

• getjtem* 

• setjtem* 

(* These methods were added by DSOM to supplement the published CORBA 1 .1 methods.) 



Overridden methods 



The following list shows all the methods overridden by the NVList class. These methods are overridden in order to modify the behavior 
defined by an ancestor class. 

• somlnit 



add item 



addjtem - Syntax 



This method adds an item to the specified NVList. 



NVList 

Environment 

Identifier 

TypeCode 

void 

long 

Flags 

ORBStatus 



receiver; 

*env; 

item_name ; 
item_type; 

* value; 
value_len ; 
item_f lags; 
rc; 



rc = add_item (receiver, env, item_name, 
item_type, value, value_len, 
item_flags) ; 



add item Parameter - receiver 



receiver (NVList) 

A pointer to the NVList object to which the item will be added. 



add item Parameter - env 



env (Environment *) 

A pointer to the Environment structure for the method caller. 



add item Parameter - item name 



item_name (Identifier) 

The name of the item to be added. 



addjtem Parameter - item_type 

item_type (TypeCode) 

The data type of the item to be added. 



add item Parameter - value 



value 

A pointer to the value of the item to be added. 



add item Parameter - value len 



valuejen (long) 

The length of the item value to be added. 



addjtem Parameter - item Jlags 



itemflags (Flags) 

A Flags bitmask (unsigned long). The /tem_f/ags can be one of the following values to indicate parameter direction 



ARGJN 

ARGJDUT 

ARGJNOUT 

IN_COPY_VALUE 

DEPENDENTJJST 



The argument is input only. 

The argument is output only. 

The argument is input/output. 

An internal copy of the argument is made and used. 

Indicates that a specified sublist must be freed when the parent list is freed. 



add item Parameter - rc 



rc (ORBStatus) 

Returns an ORBStatus value representing the return code from the operation. 




add item - Parameters 



receiver (NVList) 

A pointer to the NVList object to which the item will be added, 
env (Environment *) 

A pointer to the Environment structure for the method caller. 

item_name (Identifier) 

The name of the item to be added. 

item_type (TypeCode) 

The data type of the item to be added. 



value 

A pointer to the value of the item to be added. 

valuejen (long) 

The length of the item value to be added, 
itemflags (Flags) 

A Flags bitmask (unsigned long). The /tem_f/ags can be one of the following values to indicate parameter direction: 



ARGJN 

ARG_OUT 

ARGJNOUT 

IN_COPY_VALUE 

DEPENDENTJJST 



The argument is input only. 

The argument is output only. 

The argument is input/output. 

An internal copy of the argument is made and used. 

Indicates that a specified sublist must be freed when the parent list is freed. 



rc (ORBStatus) 

Returns an ORBStatus value representing the return code from the operation. 



add item - Remarks 



The addjtem method adds an item to the end of the specified list. 



addjtem - Original Class 

NVList 



add item - Related Methods 



Methods 



• free 

• free_memory 

• get_count 

• get_item 

• set_item 

• createjist 




addjtem - Example Code 



#include <somd.h> 

Environment ev; 

NVList plist; 

ORBStatus rc; 

rc = _create_list (SOMD_ORBOb ject , &ev, 0, &plist) ; 

rc = _add_item (plist , &ev, "firstname", TC_string, " Joe" , 

rc = _add_item (plist , &ev, "lastname", TC_string, "Schmoe 



addjtem - Topics 



Select an item: 
Syntax 
Parameters 
Returns 
Remarks 
Original Class 
Example Code 
Related Methods 
Glossary 



free 



free - Syntax 



This method frees a specified NVList. 



NVLIST 

Environment 

ORBStatus 



receiver; 

*env; 

rc; 



rc = free (receiver, env) ; 



free Parameter - receiver 



receiver (NVLIST) 

A pointer to the NVList object to be freed. 



free Parameter - env 



env (Environment *) 

A pointer to the Environment structure for the method caller. 



free Parameter - rc 



rc (ORBStatus) 

Returns an ORBStatus value representing the return code from the operation. 



free - Parameters 



receiver (NVLIST) 

A pointer to the NVList object to be freed, 
env (Environment *) 

A pointer to the Environment structure for the method caller, 
rc (ORBStatus) 

Returns an ORBStatus value representing the return code from the operation. 



free - Remarks 



The free method frees an NVList object and any associated memory. It makes an implicit call to the free_memory method. 



free - Original Class 



NVList 



free - Related Methods 




Functions 



ORBfree 



Methods 



free_memory 



free - Example Code 



#include <somd.h> 

Environment ev; 
long nargs; 

NVList arglist; 

ORBStatus rc; 

rc = _create_list (SOMD_ORBOb ject , &ev, nargs, &arglist) ; 
rc= _free (arglist , &ev) ; 



free - Topics 



Select an item: 
Syntax 
Parameters 
Returns 
Remarks 
Original Class 
Example Code 
Related Methods 
Glossary 



free_memory 



free_memory - Syntax 



This method frees any dynamically allocated out-arg memory associated with the specified list. 



NVList 



receiver; 



Environment 

ORBStatus 



env; 

rc; 



rc = free_memory (receiver, env); 



free_memory Parameter - receiver 



receiver (NVList) 

A pointer to the NVList object whose out-arg memory is to be freed. 



free_memory Parameter - env 



env (Environment *) 

A pointer to the Environment structure for the method caller. 



free_memory Parameter - rc 



rc (ORBStatus) 

Returns an ORBStatus value representing the return code from the operation. 



free_memory - Parameters 



receiver (NVList) 

A pointer to the NVList object whose out-arg memory is to be freed, 
env (Environment *) 

A pointer to the Environment structure for the method caller, 
rc (ORBStatus) 

Returns an ORBStatus value representing the return code from the operation. 



free_memory - Remarks 



The free_memory method frees any dynamically allocated out-arg memory associated with the specified list, without freeing the list object 
itself. This would be useful when invoking a Dll request multiple times with the same NVList. 



freejmemory - Original Class 

NVList 



free_memory - Related Methods 



Functions 



ORBfree 



Methods 



free 



free_memory - Example Code 



#include 

#include 

#include 

#include 



<somd . h> 

<repostry . h> 

<intf acdf . h> 

<foo.h> /* provided by user */ 



/* assume following method declaration in interface Foo : 

* long methodLong (in long inLong, inout long inoutLong) ; 

* then the following code repeatedly invokes a request: 

* result = methodLong (fooObj, &ev, 100, 200); 

* using the DI I . 

*/ 



Environment ev; 

NVList arglist; 

NamedValue result; 
long rc; 

Foo fooObj; 

Request reqObj; 

/* See example code for "invoke" to see how the argList is built */ 
/* Create the Request, reqObj */ 

rc = _create_request (fooObj, &ev, (Context *)NULL, "methodLong", 
arglist, &result, &reqObj, (Flags) 0); 

/* Repeatedly invoke the Request */ 
for (;;) { 

rc = _invoke (reqObj , &ev, (Flags) 0); 

rc = _free_memory (arglist , &ev) ; /* free out args */ 

} 



freejmemory - Topics 




Select an item: 
Syntax 
Parameters 
Returns 
Remarks 
Original Class 
Example Code 
Related Methods 
Glossary 



get_count 



get_count - Syntax 



This method returns the total number of items allocated for a list. 



NVList 

Environment 

long 

ORBStatus 



receiver; 

*env; 

count; 

rc; 



rc = get_count (receiver, env, count) ; 



get_count Parameter - receiver 



receiver (NVList) 

A pointer to the NVList object on which count is desired. 



get_count Parameter - env 



env (Environment *) 

A pointer to the Environment structure for the method caller. 



get_count Parameter - count 



count (long) 

A pointer to where the method will store the long integer count value. 



get_count Parameter - rc 



rc (ORBStatus) 

Returns an ORBStatus value representing the return code from the operation. 



get_count - Parameters 



receiver (NVList) 

A pointer to the NVList object on which count is desired, 
env (Environment *) 

A pointer to the Environment structure for the method caller, 
count (long) 

A pointer to where the method will store the long integer count value, 
rc (ORBStatus) 

Returns an ORBStatus value representing the return code from the operation. 



get_count - Remarks 



The get_count method returns the total number of allocated items in the specified list. 



get_count - Original Class 



NVList 



get_count - Related Methods 



addjtem 

getjtem 

set_item 

createjist 



Methods 




get_count - Example Code 



#include <somd.h> 

Environment ev; 

long nargs, list_size; 

NVList arglist; 

ORBStatus rc; 

rc = _create_list (SOMD_ORBOb ject , &ev, nargs, &arglist) ; 
rc = _get_count (arglist , &ev, &list_size) ; 



get_count - Topics 



Select an item: 
Syntax 
Parameters 
Returns 
Remarks 
Original Class 
Example Code 
Related Methods 
Glossary 



getjtem 



getjtem - Syntax 



This method returns the contents of a specified list item. 



NVList 

Environment 

long 

Identifier 

TypeCode 

void 

long 

Flags 

ORBStatus 



receiver; 

*env; 

item_number; 

item_name; 

item_type; 

* value; 
value_len ; 
item_f lags; 
rc; 



rc = get_item (receiver, env, item_number, 
item_name, item_type, value, 
value_len, item_flags) ; 



getjtem Parameter 



receiver 



receiver (NVList) 

A pointer to an NVList object. 



getjtem Parameter - env 



env (Environment *) 

A pointer to the Environment structure for the method caller. 



getjtem Parameter - item_number 



itemnumber (long) 

The position (index) of the item in the list. The item_number ranges from 0 to nA , where n is the total number of items in the list. 



getjtem Parameter - item_name 



item_name (Identifier) 

A pointer to where the name of the item should be returned. 



getjtem Parameter - item Jype 



item_type (TypeCode) 

A pointer to where the data type of the item should be returned. 



getjtem Parameter - value 



value 




A pointer to where a pointer to the value of the item should be returned. 



getjtem Parameter - valuejen 



valuejen (long) 

A pointer to where the length of the item value should be returned. 



getjtem Parameter - item Jlags 



item flags (Flags) 

A Flags bitmask (unsigned long). The /tem_f/ags can be one of the following values indicating parameter direction. 



ARGJN 

ARGJDUT 

ARGJNOUT 

IN_COPY_VALUE 

DEPENDENTJJST 



The argument is input only. 

The argument is output only. 

The argument is input/output. 

Indicates a copy of the argument is contained and used by the NVList. 
Indicates that a specified sublist must be freed when the parent list is freed. 



getjtem Parameter - rc 



rc (ORBStatus) 

Returns 0 for success, or a DSOM error code for failure (often because item_number+1 exceeds the number of items in the list). 



getjtem - Parameters 



receiver (NVList) 

A pointer to an NVList object. 

env (Environment *) 

A pointer to the Environment structure for the method caller. 

itemnumber (long) 

The position (index) of the item in the list. The item_number ranges from 0 to nA , where n is the total number of items in the list. 
item_name (Identifier) 

A pointer to where the name of the item should be returned. 
item_type (TypeCode) 

A pointer to where the data type of the item should be returned. 

value 

A pointer to where a pointer to the value of the item should be returned. 



valuejen (long) 




A pointer to where the length of the item value should be returned. 



item flags (Flags) 

A Flags bitmask (unsigned long). The /tem_f/ags can be one of the following values indicating parameter direction. 



ARGJN 

ARGjDUT 

ARGJNOUT 

IN_COPY_VALUE 

DEPENDENT_LIST 



The argument is input only. 

The argument is output only. 

The argument is input/output. 

Indicates a copy of the argument is contained and used by the NVList. 
Indicates that a specified sublist must be freed when the parent list is freed. 



rc (ORBStatus) 

Returns 0 for success, or a DSOM error code for failure (often because item_number+1 exceeds the number of items in the list). 



getjtem - Remarks 



The getjtem method gets an item from the specified list. Items are numbered from 0 through A/. The mode flags can be one of the 
following values: 

The getjtem method transfers ownership of storage allocated for the item value to the caller. 



getjtem - Original Class 

NVList 



getjtem - Related Methods 

Methods 

• addjtem 

• setjtem 

• createjist 



getjtem - Example Code 



#include <somd.h> 

Environment ev; 
long i , nArgs; 

ORBStatus rc; 

Identifier name; 

TypeCode typeCode; 
void *value; 
long len; 

Flags flags; 

NVList argList; 

/* get number of args */ 




rc = _get_count (argList , ev, &nArgs) ; 
for (i = 0; i 

/* get item description */ 
rc = _get_item (argList , 



getjtem - Topics 



Select an item: 
Syntax 
Parameters 
Returns 
Remarks 
Original Class 
Example Code 
Related Methods 
Glossary 



set item 



setjtem - Syntax 



This method sets the contents of an item in a list. 



rc = set_item (receiver , env, item_number. 



item_name, item_type, value, 
value_len, item_flags) ; 



&ev, 



&name, 
&typeCode 
&value, 
&len, 
&flags) ; 



NVList 

Enviornment 

long 

Identifier 

TypeCode 

void 

long 

Flags 

ORBStatus 



receiver; 

*env; 

item_number ; 
item_name; 
item_type; 
*value ; 
value_len ; 
item_f lags; 
rc; 



set item Parameter - receiver 



receiver (NVList) 

A pointer to an NVList which contains the item to be set. 



set item Parameter - env 



env (Enviornment *) 

A pointer to the Environment structure for the method caller. 



set item Parameter - item number 



itemnumber (long) 

The position (index) of the item in the list. The /tem_number ranges from 0 to n -\ , where n is the total number of items in the list. 



set item Parameter - item name 



item_name (Identifier) 

The name of the set item. 



setjtem Parameter - item_type 



item_type (TypeCode) 

The data type of the set item. 



set item Parameter - value 



value 

A pointer to the value of the set item. 



set item Parameter - value len 




valuejen (long) 

The length of the set item value. 



setjtem Parameter - item_flags 



item flags (Flags) 

A Flags bitmask (unsigned long). The /tem_f/ags can be one of the following values to indicate parameter direction: 



ARGJN 

ARGJDUT 

ARGJNOUT 

IN_COPY_VALUE 

DEPENDENT_LIST 



The argument is input only. 

The argument is output only. 

The argument is input/output. 

Indicates an internal copy of the argument is made and used. 

Indicates that a specified sublist must be freed when the parent list is freed. 



set item Parameter - rc 



rc (ORBStatus) 

Returns 0 on successful completion or a DSOM error code upon failure (often because item_number+1 exceeds the number of items 
in the list). 



set item - Parameters 



receiver (NVList) 

A pointer to an NVList which contains the item to be set. 
env (Enviornment *) 

A pointer to the Environment structure for the method caller. 

itemnumber (long) 

The position (index) of the item in the list. The /tem_number ranges from 0 to n -\ , where n is the total number of items in the list. 

item_name (Identifier) 

The name of the set item. 

item_type (TypeCode) 

The data type of the set item. 



value 

A pointer to the value of the set item. 

valuejen (long) 

The length of the set item value. 

item flags (Flags) 

A Flags bitmask (unsigned long). The /tem_f/ags can be one of the following values to indicate parameter direction: 



ARGJN 

ARGJDUT 



The argument is input only. 
The argument is output only. 




The argument is input/output. 

Indicates an internal copy of the argument is made and used. 

Indicates that a specified sublist must be freed when the parent list is freed. 



ARGJNOUT 
IN_COPY_VALUE 
DEPENDENTJJST 

rc (ORBStatus) 

Returns 0 on successful completion or a DSOM error code upon failure (often because item_number+1 exceeds the number of items 
in the list). 



set item - Remarks 



The set_item method sets the contents of an item in the list. 



setjtem - Original Class 

NVList 



set item - Related Methods 



Methods 



get_item 

addjtem 

createjist 



setjtem - Example Code 



#include <somd.h> 

Environment ev; 
long i , nArgs; 

ORBStatus rc; 

Identifier name; 

TypeCode typeCode; 
void *value; 
long len; 

Flags flags; 

NVList argList; 

/* get number of args */ 

rc = _get_count (argList , ev, &nArgs) ; 

for (i = 0; i 

/* change item description */ 
rc = _set_item (argList , 

&ev, 
i , 

name, 

typeCode, 

value. 




len, 
flags) ; 



} 



setjtem - Topics 



Select an item: 
Syntax 
Parameters 
Returns 
Remarks 
Original Class 
Example Code 
Related Methods 
Glossary 



ObjectMgr 



File stem: om 
Base 

SOMObject 

Metaclass 

SOMMSinglelnstance 

Ancestor Classes 
SOMObject 

Subclasses 

SOMDObjectMgr 

Description 

The ObjectMgr class provides a uniform, universal abstraction for any sort of object manager. Object Request Brokers, persistent storage 
managers, and OODBMSs are examples of object managers. 

This is an abstract base class, which defines the "core" interface for an object manager. It provides basic methods that: 

• Create a new object of a certain class, 

• Return a (persistent) ID for an object, 

• Return a reference to an object associated with an ID, 

• Free an object (i.e., release any local memory associated with the object without necessarily destroying the object itself), or 

• Destroy an object. 

Note: The ObjectMgr is an abstract class and should not be instantiated. Any subclass of ObjectMgr must provide implementations for all 
ObjectMgr methods. In DSOM, the class SOMDObjectMgr provides a DSOM-specific implementation. 

New methods 

The following list shows all the ObjectMgr instance methods. 

• somdDestroyObject* 

• somdGetldFromObject* 

• somdGetObjectFromID* 



• somdNewObject* 

• somdReleaseObject* 

(* This class and its methods were added by SDOM to supplement the published CORBA 1.1 interfaces.) 



somdDestroyObject 



somdDestroyObject - Syntax 



This method requests destruction of the target object. 



ObjectMgr receiver; 

Environment *env; 

SOMObject obj; 

somdDestroyObject (receiver, env, obj); 



somdDestroyObject Parameter - receiver 



receiver (ObjectMgr) 

A pointer to an ObjectMgr object. 



somdDestroyObject Parameter - env 



env (Environment *) 

A pointer to the Environment structure for the method caller. 



somdDestroyObject Parameter - obj 



obj (SOMObject) 

A pointer to the object to be freed. 



somdDestroyObject Parameter - rc 



rc 



somdDestroyObject - Parameters 



receiver (ObjectMgr) 

A pointer to an ObjectMgr object. 

env (Environment *) 

A pointer to the Environment structure for the method caller. 

obj (SOMObject) 

A pointer to the object to be freed. 



rc 



somdDestroyObject - Remarks 

The somdDestroyObject method indicates that the object manager should destroy the specified object. Storage associated with the object 
is freed. 

In DSOM, the SOMDObjectMgr forwards the deletion request to the remote server, and then frees the local proxy object. 



somdDestroyObject - Original Class 



ObjectMgr 



somdDestroyObject - Related Methods 



Methods 

• somdReleaseObject 

• somdCreateObject 

• somdTargetFree 

• release 



somdDestroyObject - Example Code 




#include <somd.h> 



Stack stk; 

Environment ev; 

SOMDServer server; 

SOM_InitEnvironment (&ev) ; 

SOMD_Init (&ev) ; 

StackNewClass (0,0); 
server = 

_somdFindAnyServerByClass (SOMD_Ob jectMgr, &ev, "Stack") ; 
stk = _somdCreateObj (server, &ev, "Stack", ""); 

_somdDestroyOb ject (SOMD_Ob jectMgr, &ev, stk); 



somdDestroyObject - Topics 



Select an item: 
Syntax 
Parameters 
Returns 
Remarks 
Original Class 
Example Code 
Related Methods 
Glossary 



somdGetldFromObject 



somdGetldFromObject - Syntax 



This method returns an ID for an object managed by a specified Object Manager. 



Ob jectMgr 
Environment 
SOMDObject 
string 



receiver; 
*env; 
ob j ; 
rc; 



rc = somdGetldFromObject (receiver , env, obj) ; 



somdGetldFromObject Parameter - receiver 



receiver (ObjectMgr) 

A pointer to an ObjectMgr object. 



somdGetldFromObject Parameter - env 



env (Environment *) 

A pointer to the Environment structure for the method caller. 



somdGetldFromObject Parameter - obj 



obj (SOMDObject) 

A pointer to the SOMDObject object for which an ID is needed. 



somdGetldFromObject Parameter - rc 



rc (string) 

Returns a string representing the ID of the specified object. 



somdGetldFromObject - Parameters 



receiver (ObjectMgr) 

A pointer to an ObjectMgr object. 

env (Environment *) 

A pointer to the Environment structure for the method caller, 
obj (SOMDObject) 

A pointer to the SOMDObject object for which an ID is needed, 
rc (string) 

Returns a string representing the ID of the specified object. 



somdGetldFromObject - Remarks 



The somdGetldFromObject method returns the persistent ID for an object managed by the specified Object Manager. This ID 
unambiguous-it always refers to the same object. 




The somdGetldFromObject method transfers ownership of storage allocated for the string to the caller. The caller should free the result 
using ORBfree function, rather than the SOMFree function. 



somdGetldFromObject - Original Class 



ObjectMgr 



somdGetldFromObject - Related Methods 



Methods 



somdGetObjectFromld 



somdGetldFromObject - Example Code 



#include <somd.h> 

#include <car.h> 

Environment ev; 

Car car; 

string somdOb jectld; 

/*note that "SOMDObject Identifiers" are just strings */ 

SOM_InitEnvironment (&ev) ; 

SOMD_Init (&ev) ; 

/* create a remote Car object */ 

car = _somdNewOb ject (SOMD_Ob jectMgr, &ev, "Car", ""); 

/* save the reference to the object */ 

somdOb jectld = _somdGetIdFromOb ject (SOMD_Ob jectMgr, &ev, car); 
FileWrite ( " /u/ joe/mycar" , somdOb jectld) ; 



somdGetldFromObject - Topics 



Select an item: 
Syntax 
Parameters 
Returns 
Remarks 
Original Class 
Example Code 
Related Methods 
Glossary 



somdGetObjectFromld 



somdGetObjectFromld - Syntax 



This method finds and activates an object implemented by a specified object manager, given its ID. 



Ob jectMgr 
Environment 
string 
SOMObject 



receiver; 

*env; 

id; 

rc; 



rc = somdGetObjectFromld (receiver , env, id); 



somdGetObjectFromld Parameter - receiver 



receiver (ObjectMgr) 

A pointer to an ObjectMgr object. 



somdGetObjectFromld Parameter - env 



env (Environment *) 

A pointer to the Environment structure for the method caller. 



somdGetObjectFromld Parameter - id 



id (string) 

A string representing an object ID. 



somdGetObjectFromld Parameter - rc 



rc (SOMObject) 

Returns a pointer to the object with the specified ID. 



somdGetObjectFromld - Parameters 



receiver (ObjectMgr) 

A pointer to an ObjectMgr object. 

env (Environment *) 

A pointer to the Environment structure for the method caller, 
id (string) 

A string representing an object ID. 
rc (SOMObject) 

Returns a pointer to the object with the specified ID. 



somdGetObjectFromld - Remarks 



The somdGetObjectFromld method finds and activates an object implemented by this object manager, given its ID. 
The somdGetObjectFromld method transfers ownership to the caller. 



somdGetObjectFromld - Original Class 

ObjectMgr 



somdGetObjectFromld - Related Methods 

Methods 

• somdGetldFromObject 



somdGetObjectFromld - Example Code 



#include <somd.h> 
#include <car.h> 
Environment ev; 

Car car; 

string somdOb jectld; 




/* restore proxy from its string form */ 

FileRead ( ”/u/ joe/mycar" , &somdOb jectld) ; 

car = _somdGetOb jectFromld (SOMD_Ob jectMgr, &ev, somdOb jectld) ; 



somdGetObjectFromld - Topics 



Select an item: 
Syntax 
Parameters 
Returns 
Remarks 
Original Class 
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somdNewObject 



somdNewObject - Syntax 



This method returns a new object of the named class. 



Ob jectMgr 

Environment 

Identifier 

string 

SOMObject 



receiver; 
*env; 
ob jclass; 
hints; 
rc; 



rc = somdNewObject (receiver, env, objclass, 
hints) ; 



somdNewObject Parameter - receiver 



receiver (ObjectMgr) 

A pointer to an ObjectMgr object. 



somdNewObject Parameter - env 



env (Environment *) 

A pointer to the Environment structure for the method caller. 



somdNewObject Parameter - objclass 



objclass (Identifier) 

An Identifier representing the type of the new object. 



somdNewObject Parameter - hints 



hints (string) 

A string which may optionally be used to specify special creation options. 



somdNewObject Parameter - rc 



rc (SOMObject) 

Returns a SOMObject. Ownership of the new object is transferred to the caller. 



somdNewObject - Parameters 



receiver (ObjectMgr) 

A pointer to an ObjectMgr object. 

env (Environment *) 

A pointer to the Environment structure for the method caller, 
objclass (Identifier) 

An Identifier representing the type of the new object, 
hints (string) 

A string which may optionally be used to specify special creation options, 
rc (SOMObject) 

Returns a SOMObject. Ownership of the new object is transferred to the caller. 



somdNewObject - Remarks 




The somdNewObject method returns a new object of the class specified by ob/c/ass. The hints field is currently ignored by the 
SOMDObjectMgr. (This field is designed so that application-specific creation options can be supplied in a later SOMobjects release.) 

In DSOM, the SOMDObjectMgr selects a random server which has advertised knowledge of the desired class ob/c/ass , and forwards the 
creation request to that server. If multiple capable servers are registered in the Implementation Repository, subsequent calls will be routed to 
different servers (starting them automatically if necessary) in order to distribute the load across several servers where possible. 



somdNewObject - Original Class 



ObjectMgr 



somdNewObject - Related Methods 



Methods 



somdDestroyObject 

somdReleaseObject 



somdNewObject - Example Code 



#include <somd.h> 

#include <stack.h> /* provided by user */ 

Stack stk; 

Environment ev; 

SOMDServer server; 

SOM_InitEnvironment (&ev) ; 

SOMD_Init ( &&ev) ; 

StackNewClass (0,0); 

stk = _somdNewOb ject (SOMD_Ob jectMgr , &ev, "Stack", ""); 
_somdDestroyOb ject (SOMD_Ob jectMgr , &ev, stk) ; 



somdNewObject - Topics 
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somdReleaseObject 



somdReleaseObject - Syntax 



This method indicates that the client has finished using the object. 



ObjectMgr receiver; 

Environment *env; 

SOMObject obj; 

somdReleaseObject (receiver , env, obj); 



somdReleaseObject Parameter - receiver 



receiver (ObjectMgr) 

A pointer to an ObjectMgr object. 



somdReleaseObject Parameter - env 



env (Environment *) 

A pointer to the Environment structure for the method caller. 



somdReleaseObject Parameter - obj 



obj (SOMObject) 

A pointer to the object to be released. 



somdReleaseObject Parameter - rc 



rc 



somdReleaseObject - Parameters 



receiver (ObjectMgr) 

A pointer to an ObjectMgr object. 

env (Environment *) 

A pointer to the Environment structure for the method caller, 
obj (SOMObject) 

A pointer to the object to be released. 



rc 



somdReleaseObject - Remarks 



The somdReleaseObject method indicates that the client has finished using the specified object. This allows the object manager to free the 
bookkeeping information associated with the object, if any. The object may also be passivated, but it is not destroyed. 

In DSOM, somdReleaseObject causes the client's proxy for the target object of interest to be freed; the target object is not freed. 



somdReleaseObject - Original Class 



ObjectMgr 



somdReleaseObject - Related Methods 



Methods 

• somdDestroyObject 

• somdNewObject 

• somdTargetFree 

• release 



somdReleaseObject - Example Code 




#include <somd.h> 
#include <car.h> 



Environment ev; 

Car car; 

string somdOb jectld; 

/* restore proxy from its string form */ 

FileRead ("/u/ joe/mycar", &somdOb jectld) ; 

car = _somdGetOb jectFromld (SOMD_Ob jectMgr, &ev, somdOb jectld) ; 
_somdReleaseOb ject (SOMD_Ob jectMgr, &ev, car); 



somdReleaseObject - Topics 
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ORB 



File stem: orb 
Base 

SOMObject 

Metaclass 

SOMMSinglelnstance 

Ancestor Classes 
SOMObject 

Description 

The ORB class implements the CORBA ORB object described in Chapter 8 of the CORBA 1.1 specification. The ORB class defines 
operations for converting object references to strings and converting strings to object references. The ORB also defines operations used by 
the Dynamic Invocation Interface for creating lists (NVLists) and determining the default context. 

New methods 

The following list shows all the ORB methods. 

• createjist 

• create_operationJist 

• get_default_context 

• object_to_string 

• string_to_object 



create list 



createjist - Syntax 



This method creates an NVList of the specified size. 



ORB 

Environment 

long 

NVList 

ORBStatus 



receiver; 
*env; 
count; 
new_list ; 
rc; 



rc = create_list (receiver, env, count, 
new_list) ; 



create list Parameter - receiver 



receiver (ORB) 

A pointer to the ORB object. 



create list Parameter - env 



env (Environment *) 

A pointer to the Environment structure for the method caller. 



create list Parameter - count 



count (long) 

An integer representing the number of elements to allocate for the list. 



create list Parameter - new list 



newjist (NVList) 

A pointer to the address where the method will store a pointer to the allocated NVList object. 



create list Parameter - rc 



rc (ORBStatus) 

Returns an ORBStatus value representing the return code of the operation. 



create list - Parameters 



receiver (ORB) 

A pointer to the ORB object. 

env (Environment *) 

A pointer to the Environment structure for the method caller, 
count (long) 

An integer representing the number of elements to allocate for the list, 
newjist (NVList) 

A pointer to the address where the method will store a pointer to the allocated NVList object, 
rc (ORBStatus) 

Returns an ORBStatus value representing the return code of the operation. 



create list - Remarks 



Creates an NVList list of the specified size, typically for use in Requests. 
Ownership of the allocated new_/ist is transferred to the caller. 



createjist - Original Class 

ORB 



create list - Related Methods 



Methods 



create_operation_list 




createjist - Example Code 



#include <somd.h> 

Environment ev; 
long nargs = 5; 

NVList arglist; 

ORBStatus rc; 

rc = _create_list (SOMD_ORBOb ject , &ev, nargs, &arglist) ; 



createjist - Topics 
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create_operationJist 



create_operationJist - Syntax 



This method creates an NVList initialized with the argument descriptions for a given operation. 



ORB 

Environment 

OperationDef 

NVList 

ORBStatus 



receiver; 
*env; 
oper; 
new_list ; 
rc; 



rc = create_operation_list (receiver, 
env, oper, new_list) ; 



create_operationJist Parameter - receiver 



receiver (ORB) 

A pointer to the ORB object. 



create_operation_list Parameter - env 



env (Environment *) 

A pointer to the Environment structure for the method caller. 



create_operation_list Parameter - oper 



oper (OperationDef) 

A pointer to the OperationDef object representing the operation for which the NVList is to be initialized 



create_operation_list Parameter - newjist 



newjist (NVList) 

A pointer to where the method will store a pointer to the resulting argument list. 



create_operation_list Parameter - rc 



rc (ORBStatus) 

Returns an ORBStatus value representing the return code of the operation. 
Ownership of the allocated new_/ist is transferred to the caller. 



create_operation_list - Parameters 



receiver (ORB) 

A pointer to the ORB object. 

env (Environment *) 

A pointer to the Environment structure for the method caller, 
oper (OperationDef) 

A pointer to the OperationDef object representing the operation for which the NVList is to be initialized 




newjist (NVList) 

A pointer to where the method will store a pointer to the resulting argument list, 
rc (ORBStatus) 

Returns an ORBStatus value representing the return code of the operation. 
Ownership of the allocated new_/ist is transferred to the caller. 



create_operation_list - Remarks 



Creates an NVList list for the specified operation, for use in Requests invoking that operation. 



create_operation_list - Original Class 

ORB 



create_operation_list - Related Methods 



Methods 



createjist 



create_operation_list - Example Code 



#include <somd.h> 

Environment ev; 

OperationDef opdef; 

NVList arglist; 
long rc; 

/* Get the OperationDef from the Interface Repository. */ 
opdef = _lookup_id (SOM_Interf aceRepository, 

&ev, "Foo: : methodLong" ) ; 

/* Create a NamedValue list for the operation. */ 

rc= _create_operation_list (SOMD_ORBOb ject , &ev, opdef, &arglist) ; 



create_operation_list - Topics 



Select an item: 




Syntax 
Parameters 
Returns 
Remarks 
Original Class 
Example Code 
Related Methods 
Glossary 



get_default_context 



get_default_context - Syntax 



This method returns the default process Context object. 



ORB 

Environment 

Context 

ORBStatus 



receiver; 

*env; 

ctx; 

rc; 



rc = get_def ault_context (receiver, env, 
ctx) ; 



get_default_context Parameter - receiver 



receiver (ORB) 

A pointer to the ORB object. 



get_default_context Parameter - env 



env (Environment *) 

A pointer to the Environment structure for the method caller. 



get_default_context Parameter - ctx 



ctx (Context) 



A pointer to where the method will store a pointer to the returned Context object. 



get_default_context Parameter - rc 



rc (ORBStatus) 

Returns an ORBStatus return code: 0 indicates success, while a non-zero value is a DSOM error code (see Chapter 6 of the SOM 
Too/k/t User's Guide ) . 



get_default_context - Parameters 



receiver (ORB) 

A pointer to the ORB object. 

env (Environment *) 

A pointer to the Environment structure for the method caller, 
ctx (Context) 

A pointer to where the method will store a pointer to the returned Context object, 
rc (ORBStatus) 

Returns an ORBStatus return code: 0 indicates success, while a non-zero value is a DSOM error code (see Chapter 6 of the SOM 
Too/k/t User's Guide ) . 



get_default_context - Remarks 



The get_default_context method gets the default process Context object. 
Ownership of the allocated Context object is transferred to the caller. 



get_default_context - Original Class 

ORB 



get_default_context - Example Code 



#include <somd.h> 

Environment ev; 
Context ext; 
long rc; 




rc = _get_default_context (SOMD_ORBOb ject , &ev, &cxt) ; 



get_default_context - Topics 



Select an item: 
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object_to_string 



object_to_string - Syntax 



This method converts an object reference to an external form (string) which can be stored outside the ORB. 



ORB 

Environment 

SOMDObject 

string 



receiver; 
*env; 
ob j ; 
rc; 



rc = ob ject_to_string (receiver, env, 
obj) ; 



object_to_string Parameter - receiver 



receiver (ORB) 

A pointer to the ORB object. 



object_to_string Parameter - env 



env (Environment *) 



A pointer to the Environment structure for the method caller. 



object_to_string Parameter - obj 



obj (SOMDObject) 

A pointer to a SOMDObject object representing the reference to be converted. 



object_to_string Parameter - rc 



rc (string) 

Returns a string representing the external (string) form of the referenced object. 



object_to_string - Parameters 



receiver (ORB) 

A pointer to the ORB object. 

env (Environment *) 

A pointer to the Environment structure for the method caller, 
obj (SOMDObject) 

A pointer to a SOMDObject object representing the reference to be converted, 
rc (string) 

Returns a string representing the external (string) form of the referenced object. 



object_to_string - Remarks 



The object_to_string method converts the object reference to a form (string) which can be stored externally. 

Ownership of allocated memory is transferred to the caller. The caller should free the result using the ORBfree function, rather than the 
SOMFree function. 



object_to_string - Original Class 



ORB 




o b j e ct_t o_s t ring - Related Methods 



Methods 



string_to_object 



object_to_string - Example Code 



#include <somd.h> 

#include <car.h> 

Environment ev; 

Car car; 

string objrefstr; 

SOM_InitEnvironment (&ev) ; 

SOMD_Init ( &ev) ; 

/* create a remote Car object */ 

car = _somdNewOb ject (SOMD_Ob jectMgr, &ev, "Car", 

/* save the reference to the object */ 

objrefstr = _ob ject_to_string (SOMD_ORBOb ject , &ev, car) ; 
FileWrite ( " /u/ joe /my car " , objrefstr) ; 



object_to_string - Topics 
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string_to_object 



string_to_object - Syntax 



This method converts an externalized (string) form of an object reference into an object reference. 



ORB 

Environment 

string 

SOMDObject 



receiver; 

*env; 

str; 

rc; 



rc = string_to_ob ject (receiver, env, 
str) ; 



string_to_object Parameter - receiver 



receiver (ORB) 

A pointer to the ORB object. 



string_to_object Parameter - env 



env (Environment *) 

A pointer to the Environment structure for the method caller. 



string_to_object Parameter - str 



str (string) 

A pointer to a character string representing the externalized form of the object reference. 



string_to_object Parameter - rc 



rc (SOMDObject) 

Returns a SOMDObject object. 



string_to_object - Parameters 



receiver (ORB) 

A pointer to the ORB object. 



env (Environment *) 



A pointer to the Environment structure for the method caller. 



str (string) 

A pointer to a character string representing the externalized form of the object reference. 

rc (SOMDObject) 

Returns a SOMDObject object. 



string_to_object - Remarks 



The string_to_object method converts the externalized (string) form of an object reference into an object reference. 



string_to_object - Original Class 

ORB 



string_to_object - Related Methods 



Methods 



object_to_string 



string_to_object - Example Code 



#include <somd.h> 

#include <car.h> 

Environment ev; 

Car car; 

string objrefstr; 

/* restore proxy from its string form */ 

FileRead ( "/u/ joe/mycar" , &objrefstr) ; 

car = _string_to_ob ject (SOMD_ORBOb ject , &ev, objrefstr); 



string_to_object - Topics 
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Principal 



File stem: principl 
Base 

SOMObject 

Metaclass 

SOMCIass 

Ancestor Classes 
SOMObject 

Description 

The Principal class defines attributes which identify the user ID and host name of the originator of a specific request. This information is 
typically used for access control. 

A Principal object is returned by the get_principal method of the SOM Object Adapter. The parameters of the get_principal method 
identify the environment and target object associated with a particular request-the SOMOA uses this information to create a Principal object 
which identifies the caller. 

Note: Details of the Principal object are not currently defined in the CORBA 1.1 specification; the attributes which have been defined are 
required by DSOM. 

Attributes 

Listed below is each available attribute, with its corresponding type in parentheses, followed by a description of its purpose: 
userName (string) 

Identifies the name of the user associated with the request invocation. (Currently, this value is obtained from the USER 
environment variable in the process which invoked the request.) 

hostName (string) 

Identifies the name of the host from where the request originated. (Currently, this value is obtained from the HOSTNAME 
environment variable in the process which invoked the request.) 



Request 



File stem: request 
Base 

SOMObject 

Metaclass 

SOMCIass 



Ancestor Classes 
SOMObject 



Description 



The Request class implements the CORBA Request object described in section 6.2 on page 108 of CORBA 1 .1 . The Request object is 
used by the dynamic invocation interface to dynamically create and issue a request to a remote object. Request objects are created by the 

create_request method in SOMDObject. 

New methods 

The following list shows all the Request methods. 

• add_arg 

• destroy* 

• get_response 

• invoke 

• send 

(* The destroy method was defined as delete in CORBA 1.1, which conflicts with the delete operator in C++ ** However, there is a 
Request_delete macro defined for CORBA compatibility.) 

Overridden methods 

The following list shows all the methods overridden by the Request class. These methods are overridden in order to modify the behavior 
defined by an ancestor class. 

■ somlnit 

• somUninit 



add_arg 



add_arg - Syntax 



This method incrementally adds an argument to a Request object. 



Request 

Environment 

Identifier 

TypeCode 

void 

long 

Flags 

ORBStatus 



receiver; 

*env; 
name ; 
arg_type; 

* value; /* A pointer to the argument value to be added. */ 

len; 

arg_f lags; 
rc; 



rc = add_arg (receiver , env, name, arg_type, 
value, len, arg_flags) ; 



add_arg Parameter - receiver 



receiver (Request) 

A pointer to a Request object. 



add_arg Parameter - env 



env (Environment *) 

A pointer to the Environment structure for the method caller. 



add_arg Parameter - name 



name (Identifier) 

An identifier representing the name of the argument to be added. 



add_arg Parameter - arg_type 



arg type (TypeCode) 

The typecode for the argument to be added. 



add_arg Parameter - value 



value 

A pointer to the argument value to be added. 



add_arg Parameter - len 



len (long) 

The length of the argument. 



add_arg Parameter - argflags 



argflags (Flags) 

A Flags bitmask (unsigned long). The arg_f/ags parameter may take one of the following values to indicate parameter direction 




ARGJN 

ARG_OUT 

INOUT 

IN_COPY_VALUE 

DEPENDENT_LIST 



The argument is input only. 

The argument is output only. 

The argument is input/output. 

An internal copy of the argument is to be made and used. 

Indicates that a specified sublist must be freed when the parent list is freed. 



add_arg Parameter - rc 



rc (ORBStatus) 

Returns an ORBStatus value representing the return code of the operation. 



add_arg - Parameters 



receiver (Request) 

A pointer to a Request object. 

env (Environment *) 

A pointer to the Environment structure for the method caller, 
name (Identifier) 

An identifier representing the name of the argument to be added, 
arg type (TypeCode) 

The typecode for the argument to be added. 



value 

A pointer to the argument value to be added, 
len (long) 

The length of the argument, 
arg flags (Flags) 

A Flags bitmask (unsigned long). The arg_f/ags parameter may take one of the following values to indicate parameter direction 



ARGJN 

ARG_OUT 

INOUT 

IN_COPY_VALUE 
DEPENDENT JJST 



The argument is input only. 

The argument is output only. 

The argument is input/output. 

An internal copy of the argument is to be made and used. 

Indicates that a specified sublist must be freed when the parent list is freed. 



rc (ORBStatus) 

Returns an ORBStatus value representing the return code of the operation. 



add_arg - Remarks 



The add_arg method incrementally adds an argument to a Request object. The Request object must have been created using the 
create_request method with an empty argument list. 



add_arg - Original Class 




Request 



add_arg - Example Code 



#include 

#include 

#include 

#include 



<somd . h> 

<repostry . h> 
cintf acdf . h> 

<foo.h> /* provided by user */ 



/* assume following method declaration in interface Foo: 

* long methodLong (in long inLong, inout long inoutLong) ; 

* then the following code builds a request to execute the call: 

* result = methodLong ( fooObj , &ev, 100,200); 

*using the DII . 

*/ 



Environment ev; 

OperationDef opdef; 

Description desc; 

OperationDescription *opdesc; 
long rc; 

long valuel = 100; 
long value2 = 200; 

Foo fooObj; 

Request reqObj; 

NamedValue result; 

/* Get the OperationDef from the Interface Repository. */ 
opdef = _lookup_id (SOM_Interf aceRepository, 

&ev, "Foo : imethodLong" ) ; 

/* Get the operation description structure. */ 
desc = _describe (opdef, &ev) ; 

opdesc = (OperationDescription *) desc .value ._value; 

/* Fill in the TypeCode field for result. */ 
result . argument ._type = opdesc->result ; 

/* Create the Request, reqObj */ 

rc = _create_request (fooObj, &ev, (Context* ) NULL, "methodLong", 
(NVList * ) NULL, &result, &reqObj, (Flags) 0) 

/* Add argl info onto the request */ 

_add_arg (reqObj, &ev, 

"inLong", TC_long, &valuel, sizeof (long) , (Flags) 0) ; 

/* Add arg2 info onto the request */ 

_add_arg (reqObj, &ev, 

"inoutLong", TC_long, &value2, sizeof (long) , (Flags) 0) 



add_arg - Topics 



Select an item: 
Syntax 
Parameters 
Returns 
Remarks 
Original Class 
Example Code 
Glossary 



destroy 



destroy - Syntax 



This method deletes the memory allocated by the ORB for a Request object. 



Request receiver; 

Environment *env; 

ORBStatus rc; 

rc = destroy (receiver , env) ; 



destroy Parameter - receiver 



receiver (Request) 

A pointer to a Request object. 



destroy Parameter - env 



env (Environment *) 

A pointer to the Environment structure for the method caller. 



destroy Parameter - rc 



rc (ORBStatus) 

Returns an ORBStatus value representing the return code of the operation. 



destroy - Parameters 



receiver (Request) 

A pointer to a Request object. 

env (Environment *) 

A pointer to the Environment structure for the method caller, 
rc (ORBStatus) 

Returns an ORBStatus value representing the return code of the operation. 



destroy - Remarks 



The destroy method deletes the Request object and all associated memory. 

Note: This method is called "delete" in the CORBA 1 .1 specification. However, the word "delete" is a reserved operator in C++, so the name 
"destroy" was chosen as an alternative. For CORBA compatibility, a macro defining Request_delete as an alias for destroy has been 
included in the C header files. 



destroy - Original Class 



Request 



destroy - Related Methods 



Methods 

• invoke 

• send 

• get_response 



destroy - Example Code 



#include 

#include 

#include 

#include 



<somd . h> 
crepostry . h> 
cintf acdf . h> 

<foo.h> /* provided by user */ 



/* assume following method declaration in interface Foo : 

* long methodLong (in long inLong, inout long inoutLong) ; 

* then the following code sends a request to execute the call: 

* result = methodLong (fooObj, &ev, 100,200); 

* using the DII without waiting for the result. Then, later, 

* waits for and then uses the result. 

*/ 

Environment ev; 

NVList arglist; 
long rc; 

Foo fooObj; 

Request reqObj; 




NamedValue result; 



/* see the Example code for invoke to see how the request 
* is built 
*/ 

/* Create the Request, reqObj */ 

rc = _create_request (fooObj, Sev, (Context *)NULL, "methodLong" , 
arglist, Sresult, SreqObj, (Flags) 0) ; 

/* Finally, send the request */ 
rc = _send (reqObj , Sev, (Flags) 0) ; 

/* do some work, i.e. don't wait for the result */ 

/* wait here for the result of the request */ 
rc = _get_response (reqObj , Sev, (Flags) 0) ; 

/* use the result */ 

if (result->argument ._value == 9600) (...) 

/* throw away the reqObj */ 

_destroy (reqObj, Sev) ; 



destroy - Topics 



Select an item: 
Syntax 
Parameters 
Returns 
Remarks 
Original Class 
Example Code 
Related Methods 
Glossary 



get_response 



get_response - Syntax 



This method determines whether an asynchronous Request has completed. 



Request 

Environment 

Flags 

ORBStatus 



receiver; 

*env; 

response_f lags ; 
rc; 



rc = get_response (receiver, env, response_f lags) ; 



get_response Parameter - receiver 



receiver (Request) 

A pointer to a Request object. 



get_response Parameter - env 



env (Environment *) 

A pointer to the Environment structure for the method caller. 



get_response Parameter - response_flags 



response_flags (Flags) 

A Flags bitmask (unsigned long) containing control information for the get_response method. The response_f/ags argument may 
have the following value: 

RESP_NO_WAIT Indicates the caller does not want to wait for a response. 



get_response Parameter - rc 



rc (ORBStatus) 

Returns an ORBStatus value representing the return code of the operation. 



get_response - Parameters 



receiver (Request) 

A pointer to a Request object. 

env (Environment *) 

A pointer to the Environment structure for the method caller. 

response_flags (Flags) 

A Flags bitmask (unsigned long) containing control information for the get_response method. The response_f/ags argument may 
have the following value: 

RESP_NO_WAIT Indicates the caller does not want to wait for a response, 

rc (ORBStatus) 

Returns an ORBStatus value representing the return code of the operation. 




get_response - Remarks 



The get_response method determines whether the asynchronous Request has completed. 



get_response - Original Class 



Request 



get_response - Related Methods 



Methods 



invoke 

send 



Macros 



Request_delete 



get_response - Example Code 



#include 

#include 

#include 

#include 



<somd . h> 

<repostry . h> 

<intf acdf . h> 

<foo.h> /* provided by user */ 



/* assume following method declaration in interface Foo : 

* long methodLong (in long inLong, inout long inoutLong) ; 

* then the following code sends a request to execute the call: 

* result = methodLong (fooObj, &ev, 100,200); 

* using the DII without waiting for the result. Then, later, 

* waits for and then uses the result. 

*/ 



Environment ev; 

NVList arglist; 
long rc; 

Foo fooObj; 

Request reqObj; 

NamedValue result; 

/* see the Example code for invoke to see how the request 
* is built 
*/ 



/* Create the Request, reqObj */ 

rc = _create_request (fooObj, &ev, (Context *)NULL, "methodLong", 
arglist, &result, &reqObj, (Flags) 0); 




/* Finally, send the request */ 
rc = _send (reqOb j , Sev, (Flags) 0) ; 

/* do some work, i.e. don't wait for the result */ 

/* wait here for the result of the request */ 
rc = _get_response (reqOb j, Sev, (Flags) 0) ; 

/* use the result */ 

if (result->argument ._value == 9600) (...) 



get_response - Topics 



Select an item: 
Syntax 
Parameters 
Returns 
Remarks 
Original Class 
Example Code 
Related Methods 
Glossary 



invoke 



invoke - Syntax 



This method invokes a Request synchronously, waiting for the response. 



Request 

Environment 

Flags 

ORBStatus 



receiver; 

*env; 

invoke_f lags ; 
rc; 



rc = invoke (receiver, env, invoke_f lags) ; 



invoke Parameter - receiver 



receiver (Request) 

A pointer to a Request object. 



invoke Parameter - env 



env (Environment *) 

A pointer to the Environment structure for the method caller. 



invoke Parameter - invoke_flags 



invoke_flags (Flags) 

A Flags bitmask (unsigned long) representing control information for the invoke method. There are currently no flags defined for the 
invoke method. 



invoke Parameter - rc 

rc (ORBStatus) 

Returns an ORBStatusvalue representing the return code of the operation. 



invoke - Parameters 



receiver (Request) 

A pointer to a Request object. 

env (Environment *) 

A pointer to the Environment structure for the method caller. 
invoke_flags (Flags) 

A Flags bitmask (unsigned long) representing control information for the invoke method. There are currently no flags defined for the 
invoke method. 

rc (ORBStatus) 

Returns an ORBStatusvalue representing the return code of the operation. 



invoke - Remarks 



The invoke method sends a Request synchronously, waiting for the response. 



invoke - Original Class 




Request 



invoke - Related Methods 



Methods 

• send 

• get_response 

Macros 



Request_delete 



invoke - Example Code 



#include 

#include 

#include 

#include 



<somd . h> 

<repostry . h> 

<intf acdf . h> 

<foo.h> /* provided by user */ 



/* assume following method declaration in interface Foo : 

* long methodLong (in long inLong, inout long inoutLong) ; 

* then the following code builds and then invokes 

* a request to execute the call: 

* result = methodLong (fooObj, &ev, 100,200); 

* using the DI I . 

*/ 



Environment ev; 

OperationDef opdef; 

Description desc; 

OperationDescription *opdesc; 

NVList arglist; 
long rc; 

long valuel = 100; 
long value2 = 200; 

Foo fooObj; 

Request reqObj; 

NamedValue result; 

Identifier name; 

TypeCode tc; 
void * dummy; 
long dummy len; 

Flags flags; 

/* Get the OperationDef from the Interface Repository. */ 
opdef = _lookup_id (SOM_Interf aceRepository, 

&ev, "Foo: : methodLong" ) ; 

/* Create a NamedValue list for the operation. */ 

rc= _create_operation_list (SOMD_ORBOb ject , &ev, opdef, &arglist) 

/* Insert argl info into arglist */ 

_get_item (arglist , &ev, 

0, &name, &tc, & dummy, & dummy len, & flags) ; 

_set_item (arglist, &ev, 0, name, tc, &valuel, sizeof (long) , flags) 

/* Insert arg2 info into arglist */ 

_get_item (arglist , &ev, 

1, &name, &tc, & dummy, & dummy len, & flags) ; 




_set_item (arglist , &ev, 1 , name, tc, &value2, sizeof (long) , flags) 

/* Get the operation description structure. */ 
desc = _describe (opdef , &ev) ; 

opdesc = (OperationDescription *) desc . value ._value; 

/* Fill in the TypeCode field for result. */ 
result . argument ._type = opdesc->result ; 

/* Create the Request, reqObj */ 

rc = _create_request (fooOb j, &ev, (Context *)NULL, "methodLong" , 
arglist, &result, &reqObj, (Flags) 0); 

/* Finally, invoke the request */ 
rc = _invoke (reqObj , &ev, (Flags) 0) ; 

/* Print results */ 

printf ( "result : %d, value2 : %d\n" , 

* (long*) (result . argument ._value) , 
value2 ) ; 



invoke - Topics 



Select an item: 
Syntax 
Parameters 
Returns 
Remarks 
Original Class 
Example Code 
Related Methods 
Glossary 



send 



send - Syntax 



This method invokes a Request asynchronously. 



Request 

Environment 

Flags 

ORBStatus 



receiver; 

*env; 

invoke_f lags ; 
rc; 



rc = send (receiver , env, invoke_f lags) ; 



send Parameter - receiver 



receiver (Request) 

A pointer to a Request object. 



send Parameter - env 



env (Environment *) 

A pointer to the Environment structure for the method caller. 



send Parameter - invoke_flags 



invoke_flags (Flags) 

A Flags bitmask (unsigned long) containing send method control information. The argument /nvoke_f/ags can have the following 
value. 

INV_NO_RESPONSE Indicates that the invoker does not intend to wait for a response, nor does it expect any of the output 

arguments (inout or out) to be updated. 



send Parameter - rc 



rc (ORBStatus) 

Returns an ORBStatus value representing the return code from the operation. 



send - Parameters 



receiver (Request) 

A pointer to a Request object. 

env (Environment *) 

A pointer to the Environment structure for the method caller. 

invoke_flags (Flags) 

A Flags bitmask (unsigned long) containing send method control information. The argument /nvoke_f/ags can have the following 
value. 

INV_NO_RESPONSE Indicates that the invoker does not intend to wait for a response, nor does it expect any of the output 

arguments (inout or out) to be updated. 

rc (ORBStatus) 

Returns an ORBStatus value representing the return code from the operation. 




send - Remarks 



The send method invokes the Request asynchronously. The response must eventually be checked by invoking either the get_response 
method or the get_next_response function. 



send - Original Class 

Request 

send - Related Methods 

Methods 

• invoke 

• get_response 

Macros 

• Request_delete 



send - Example Code 



#include 

#include 

#include 

#include 



<somd . h> 

<repostry . h> 
cintf acdf . h> 

<foo.h> /* provided by user */ 



/* assume following method declaration in interface Foo : 

* long methodLong (in long inLong, inout long inoutLong) ; 

* then the following code sends 

* a request to execute the call: 

* result = methodLong (fooObj, &ev, 100,200); 

* using the DI I . 

*/ 



Environment ev; 

NVList arglist; 
long rc; 

Foo fooObj; 

Request reqObj; 

NamedValue result; 

/* see the Example code for invoke to see how the request 
* is built 
*/ 



/* Create the Request, reqObj */ 

rc = _create_request (fooObj, &ev, (Context *) NULL, "methodLong" , 

arglist, &result, &reqObj, (Flags) 0); 




/* Finally, send the request */ 
rc = _send (reqOb j , &ev, (Flags) 0) ; 



send - Topics 



Select an item: 
Syntax 
Parameters 
Returns 
Remarks 
Original Class 
Example Code 
Related Methods 
Glossary 



SOMDClientProxy 



File stem: somdcprx 
Base 

SOMDObject 

Metaclass 

SOMCIass 

Ancestor Classes 
SOMObject 

SOMDObject 

Description 

The SOMDClientProxy class implements DSOM proxy objects in Clients. SOMDClientProxy overrides the usual somDispatch methods 
with versions that build a DSOM Request for remote invocation and dispatch it to the remote object. It is intended that the implementation of 
this "generic" proxy class will be used to derive specific proxy classes via multiple inheritance. The remote dispatch method is inherited from 
this client proxy class, while the desired interface and language bindings are inherited from the target class (but not the implementation). 



SOMDClientProxy Animal 



Animal_P roxy 



New methods 

The following list shows all the SOMDClientProxy methods. 

• somdProxyFree* 

• somdProxyGetClass* 

• somdProxyGetClassName* 

• somdTargetFree* 

• somdTargetGetClass* 

• somdTargetGetClassName* 

• somdReleaseResources* 



(* This class and its methods were added by DSOM to supplement the published CORBA'1 .1 interfaces.) 

Overridden methods 



The following list shows all the methods overridden by the SOMDClientProxy class. These methods are overridden in order to modify the 
behavior defined by an ancestor class. 



• create_request 

• create_request_args 

• is_proxy 

• release 

• somDispatch 

• somDispatchA 

• somDispatchD 

• somDispatchL 

• somDispatchV 

• somFree 

• somGetClass 

• somGetClassName 

■ somlnit 

• somUninit 



somdProxyFree 



somdProxyFree - Syntax 



This method executes somFree on the local proxy object. 

SOMDClientProxy receiver; 

Environment *env; 

somdProxyFree (receiver, env) ; 



somdProxyFree Parameter - receiver 



receiver (SOMDClientProxy) 

A pointer to the SOMDClientProxy object. 



somdProxyFree Parameter - env 



env (Environment *) 

A pointer to the Environment structure for the method caller. 



somdProxyFree Parameter - rc 



somdProxyFree - Parameters 



receiver (SOMDClientProxy) 

A pointer to the SOMDClientProxy object. 



env (Environment *) 

A pointer to the Environment structure for the method caller. 



rc 



somdProxyFree - Remarks 



The somdProxyFree method executes the somFree method call on the local proxy object. This method has been provided when the 
application program wants to be explicit about freeing the proxy object vs. the target object. 



somdProxyFree - Original Class 



SOMDClientProxy 



somdProxyFree - Related Methods 



Methods 

• release 

• somdReleaseObject 



somdProxyFree - Example Code 




#include <somd.h> 
#include <car.h> 



Environment ev; 

Car car; 

string somdOb jectld; 

/* restore proxy from its string form */ 

FileRead ( "/u/ joe/mycar" , &somdOb jectld) ; 

car = _somdGetOb jectFromld (SOMD_Ob jectMgr, &ev, somdOb jectld) ; 

_somdProxyFree (car, &ev) ; 



somdProxyFree - Topics 



Select an item: 
Syntax 
Parameters 
Returns 
Remarks 
Original Class 
Example Code 
Related Methods 
Glossary 



somdProxyGetClass 



somdProxyGetClass - Syntax 



This method returns the class object for the local proxy object. 



SOMDClientProxy receiver; 
Environment *env; 

SOMClass rc; 

rc = somdProxyGetClass (receiver, env) ; 



somdProxyGetClass Parameter - receiver 



receiver (SOMDClientProxy) 

A pointer to the SOMDClientProxy object. 



somdProxyGetClass Parameter - env 



env (Environment *) 

A pointer to the Environment structure for the method caller. 



somdProxyGetClass Parameter - rc 



rc (SOMCIass) 

Returns a pointer to the class object for the local proxy object. 



somdProxyGetClass - Parameters 



receiver (SOMDClientProxy) 

A pointer to the SOMDClientProxy object. 

env (Environment *) 

A pointer to the Environment structure for the method caller, 
rc (SOMCIass) 

Returns a pointer to the class object for the local proxy object. 



somdProxyGetClass - Remarks 



The somdProxyGetClass method executes the somGetClass method call on the local proxy object and returns a pointer to the proxy's 
class object. This method has been provided when the application program wants to be explicit about getting the class object for the proxy 
objectvs. the target object. 



somdProxyGetClass - Original Class 

SOMDClientProxy 



somdProxyGetClass - Example Code 




#include <somd.h> 

#include <car.h> 

Environment ev; 

Car car; 

SOMClass carProxyClass; 
string somdOb jectld; 

/* restore proxy from its string form */ 

FileRead ( " /u/ joe/mycar" , &somdOb jectld) ; 

car = _somdGetOb jectFromld (SOMD_Ob jectMgr, &ev, somdOb jectld) ; 
carProxyClass = _somdProxyGetClass (car, &ev) ; 



somdProxyGetClass - Topics 



Select an item: 
Syntax 
Parameters 
Returns 
Remarks 
Original Class 
Example Code 
Glossary 



somdProxyGetClassName 



somdProxyGetClassName - Syntax 



This method returns the class name for the local proxy object. 



SOMDClientProxy receiver; 

Environment *env; 

string rc; 

rc = somdProxyGetClassName (receiver, env) ; 



somdProxyGetClassName Parameter - receiver 



receiver (SOMDClientProxy) 

A pointer to the SOMDClientProxy object for the desired remote target object. 



somdProxyGetClassName Parameter - env 



env (Environment *) 

A pointer to the Environment structure for the method caller. 



somdProxyGetClassName Parameter - rc 



rc (string) 

Returns a string containing the class name of the local proxy object. 



somdProxyGetClassName - Parameters 



receiver (SOMDClientProxy) 

A pointer to the SOMDClientProxy object for the desired remote target object, 
env (Environment *) 

A pointer to the Environment structure for the method caller, 
rc (string) 

Returns a string containing the class name of the local proxy object. 



somdProxyGetClassName - Remarks 



The somdProxyGetClassName method executes the somGetClassName method call on the local proxy object and returns the proxy's 
class name. This method has been provided when the application program wants to be explicit about getting the class name of the proxy 
object vs. the target object. 



somdProxyGetClassName - Original Class 



SOMDClientProxy 



somdProxyGetClassName - Example Code 



#include <somd.h> 




#include 



Environment ev; 

Car car; 

string carProxyClassName; 
string somdOb jectld; 

/* restore proxy from its string form */ 

FileRead ( "/u/ joe/mycar" , &somdOb jectld) ; 

car = _somdGetOb jectFromld (SOMD_Ob jectMgr, &ev, somdOb jectld) ; 
carProxyClassName = _somdProxyGetClassName (car, &ev) ; 



somdProxyGetClassName - Topics 



Select an item: 
Syntax 
Parameters 
Returns 
Remarks 
Original Class 
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somdReleaseResources 



somdReleaseResources - Syntax 



This method instructs a proxy object to release any memory it is holding as a result of a remote method invocation in which a parameter or 
result was designated as "object-owned". 



SOMDClientProxy receiver; 
Environment *env; 

somdReleaseResources (receiver, env) ; 



somdReleaseResources Parameter - receiver 



receiver (SOMDClientProxy) 

A pointer to the SOMDClientProxy object to release resources. 



somdReleaseResources Parameter 



env 



env (Environment *) 

A pointer to the Environment structure for the method call. 



somdReleaseResources Parameter - rc 



rc 



somdReleaseResources - Parameters 



receiver (SOMDClientProxy) 

A pointer to the SOMDClientProxy object to release resources, 
env (Environment *) 

A pointer to the Environment structure for the method call. 



rc 



somdReleaseResources - Remarks 



The somdReleaseResources method instructs a proxy object to release any memory it is holding as a result of a remote method invocation 
in which a parameter or result was designated as "object-owned". 

When a DSOM client program makes a remote method invocation, via a proxy, and the method being invoked has an object-owned 
parameter or return result, the client-side memory associated with the parameter/result will be owned by the caller's proxy, and the 
server-side memory will be owned by the remote object. The memory owned by the caller's proxy will be freed when the proxy is released by 
the client program. (The time at which the server-side memory will be freed depends on the implementation of the remote object.) 

A DSOM client can also instruct a proxy object to free all memory that it owns on behalf of the client without releasing the proxy (assuming 
that the client program is finished using the object-owned memory), by invoking the somdReleaseResources method on the proxy object. 
Calling somdReleaseResources can prevent unused memory from accumulating in a proxy. 

For example, consider a client program repeatedly invoking a remote method "get_string", which returns a string that is designated (in SOM 
IDL) as "object-owned". The proxy on which the method is invoked will store the memory associated with all of the returned strings, even if 
the strings are not unique, until the proxy is released. If the client program only uses the last result returned from "get_string", then unused 
memory accumulates in the proxy. The client program can prevent this by invoking somdReleaseResources on the proxy object 
periodically (for example, each time it finishes using the result of the last "get_string" call). 



somdReleaseResources - Original Class 




SOMDClientProxy 



somdReleaseResources - Related Methods 



Methods 



release 



somdReleaseResources - Example Code 



string mystring; 

/* remote invocation of get_string on proxy x, 

* where method get_string has the SOM IDL modifier 

* "ob ject_owns_result " . 

*/ 

mystring = X_get_string (x, ev) ; 

/* ... use mystring ... */ 

/* when finished using mystring, instruct the 

* proxy that it can free it. 

*/ 

_somdReleaseResources (x, ev) ; 



somdReleaseResources - Topics 



Select an item: 
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somdTargetFree 



somdTargetFree - Syntax 



This method forwards the somFree method call to the remote target object. 



SOMDClientProxy receiver; 
Environment *env; 

somdTargetFree (receiver, env) ; 



somdTargetFree Parameter - receiver 



receiver (SOMDClientProxy) 

A pointer to the SOMDClientProxy object for the desired remote target object. 



somdTargetFree Parameter - env 



env (Environment *) 

A pointer to the Environment structure for the method caller. 



somdTargetFree Parameter - rc 



somdTargetFree - Parameters 



receiver (SOMDClientProxy) 

A pointer to the SOMDClientProxy object for the desired remote target object, 
env (Environment *) 

A pointer to the Environment structure for the method caller. 



rc 



somdTargetFree - Remarks 



The somdTargetFree method forwards the somFree method call to the remote target object. This method has been provided when the 
application program wants to be explicit about freeing the remote target object vs. the proxy object. 



somdTargetFree - Original Class 



SOMDClientProxy 



somdTargetFree - Related Methods 



Methods 



release 

somdDestroyObject 



somdTargetFree - Example Code 



#include <somd.h> 

#include <car.h> 

Environment ev; 

Car car; 

string somdOb jectld; 

/* restore proxy from its string form */ 

FileRead ( "/u/ joe/mycar" , &somdOb jectld) ; 

car = _somdGetOb jectFromld (SOMD_Ob jectMgr, &ev, somdOb jectld) ; 

_somdTargetFree (car, &ev) ; 



somdTargetFree - Topics 



Select an item: 
Syntax 
Parameters 
Returns 
Remarks 
Original Class 
Example Code 
Related Methods 
Glossary 



somdT argetGetClass 



somdTargetGetClass - Syntax 



This method returns (a proxy for) the class object for the remote target object. 



SOMDClientProxy receiver; 

Environment *env; 

SOMClass rc; 

rc = somdTargetGetClass (receiver, env) ; 



somdTargetGetClass Parameter - receiver 



receiver (SOMDClientProxy) 

A pointer to the SOMDClientProxy object for the desired remote target object. 



somdTargetGetClass Parameter - env 



env (Environment *) 

A pointer to the Environment structure for the method caller. 



somdTargetGetClass Parameter - rc 



rc (SOMClass) 

Returns a pointer to the class object for the remote target object. 



somdTargetGetClass - Parameters 



receiver (SOMDClientProxy) 

A pointer to the SOMDClientProxy object for the desired remote target object, 
env (Environment *) 

A pointer to the Environment structure for the method caller. 



rc (SOMCIass) 

Returns a pointer to the class object for the remote target object. 



somdTargetGetClass - Remarks 



The somdTargetGetClass method forwards the somGetClass method call to the remote target object and returns a pointer to the class 
object for that object. This method has been provided when the application program wants to be explicit about getting the class object for the 
remote target object vs. the local proxy. 



somdTargetGetClass - Original Class 



SOMDClientProxy 



somdTargetGetClass - Related Methods 



Methods 



somdProxyGetClass 



somdTargetGetClass - Example Code 



#include <somd.h> 

#include <car.h> 

Environment ev; 

Car car; 

SOMCIass carClass; 
string somdOb jectld; 

/* restore proxy from its string form */ 

FileRead (" /u/ joe/mycar", &somdOb jectld) ; 

car = _somdGetOb jectFromld (SOMD_Ob jectMgr, &ev, somdOb jectld) ; 
carClass = _somdTargetGetClass (car , &ev) ; 



somdTargetGetClass - Topics 



Select an item: 

Syntax 

Parameters 



Returns 
Remarks 
Original Class 
Example Code 
Related Methods 
Glossary 



somdT argetGetClassName 



somdTargetGetClassName - Syntax 



This method returns the class name for the remote target object. 



SOMDClientProxy receiver; 

Environment *env; 

string rc; 

rc = somdTargetGetClassName (receiver , env) ; 



somdTargetGetClassName Parameter - receiver 



receiver (SOMDClientProxy) 

A pointer to the SOMDClientProxy object for the desired remote target object. 



somdTargetGetClassName Parameter - env 



env (Environment *) 

A pointer to the Environment structure for the method caller. 



somdTargetGetClassName Parameter - rc 



rc (string) 

Returns a string containing the class name of the remote target object. 



somdTargetGetClassName - Parameters 



receiver (SOMDClientProxy) 

A pointer to the SOMDClientProxy object for the desired remote target object, 
env (Environment *) 

A pointer to the Environment structure for the method caller, 
rc (string) 

Returns a string containing the class name of the remote target object. 



somdTargetGetClassName - Remarks 



The somdTargetGetClassName method forwards the somGetClassName method call to the remote target object and returns the class 
name for that object. This method has been provided when the application program wants to be explicit about getting the class name of the 
remote target object vs. the proxy object. 



somdTargetGetClassName - Original Class 



SOMDClientProxy 



somdTargetGetClassName - Related Methods 



Methods 



somdProxyGetClassName 



somdTargetGetClassName - Example Code 



#include <somd.h> 

#include <car.h> 

Environment ev; 

Car car; 

string carClassName; 
string somdOb jectld; 

/* restore proxy from its string form */ 

FileRead ("/u/ joe/mycar", &somdOb jectld) ; 

car = _somdGetOb jectFromld (SOMD_Ob jectMgr, &ev, somdOb jectld) ; 
carClassName = _somdTargetGetClassName (car , &ev) ; 




somdTargetGetClassName - Topics 



Select an item: 
Syntax 
Parameters 
Returns 
Remarks 
Original Class 
Example Code 
Related Methods 
Glossary 



SOMDObject 



File stem: somdobj 
Base 

SOMObject 

Metaclass 

SOMCIass 

Ancestor Classes 
SOMObject 

Description 

The SOMDObject class implements the methods that can be applied to all CORBA object references: e.g., getjmplementation, 
getjnterface, is_nil, duplicate, and release. In the CORBA 1.1 specification, these methods are described in Chapter 8. 

In DSOM, there is also another derivation of this class: SOMDClientProxy. This subclass inherits the implementation of SOMDObject, but 
extends it by overriding somDispatch with a "remote dispatch" method, and caches the binding to the server process. Whenever a remote 
object is accessed, it is represented in the client process by a SOMDClientProxy object. 

New methods 

The following list shows all the SOMDObject methods. 

• create_request 

• create_request_args* 

• duplicate 

• getjmplementation 

• getjnterface 

• is_constant* 

• is_nil 

• is_proxy* 

• is_SOM_ref* 

• release 

(* These methods were added by DSOM to supplement the published CORBA 1.1 interfaces.) 

Overridden methods 

The following list shows all the methods overridden by the SOMDObject class. These methods are overridden in order to modify the 
behavior defined by an ancestor class. 



somlnit 

somUninit 

somDumpSelflnt 



create_request 



create_request - Syntax 



This method creates a request to execute a particular operation on the referenced object. 



SOMDObject 

Environment 

Context 

Identifier 

NVList 

NamedValue 

Request 

Flags 

ORBStatus 



receiver; 

*env; 

ctx; 

operation; 
arg_list ; 
result; 
request; 
req_f lags; 
rc; 



rc = create_request (receiver, env, ctx, 

operation, arg_list, result, request, 
req_flags) ; 



create_request Parameter - receiver 



receiver (SOMDObject) 

A pointer to a SOMDObject object. 



create_request Parameter - env 



env (Environment *) 

A pointer to the Environment structure for the method caller. 



create_request Parameter - ctx 



ctx (Context) 

A pointer to the Context object of the requested operation. 



create_request Parameter - operation 



operation (Identifier) 

The name of the operation to be performed on the target object, receiver. 



create_request Parameter - arg Jist 



argjist (NVList) 

A pointer to a list of arguments (NVList). If this argument is NULL, the argument list can be assembled by repeated calls to the 
add_arg method on the Request object created by calling this method. 



create_request Parameter - result 



result (NamedValue) 

A pointer to a NamedValue structure where the result of applying operation to receiver should be stored. 



create_request Parameter - request 



request (Request) 

A pointer to storage for the address of the created Request object. 



create_request Parameter - req_flags 



req_flags (Flags) 

A Flags bitmask (unsigned long) that may contain the following flag value: 

OUT_LIST_MEMORY Indicates that any out-arg memory is associated with the argument list. When the list structure 

freed, any associated out-arg memory is also freed, if OUT_LIST_MEMORY is specified, an 
argument list must also have been specified on the create_request call. 




create_request Parameter - rc 



rc (ORBStatus) 

Returns an ORBStatus value as the status code for the request. 



create_request - Parameters 



receiver (SOMDObject) 

A pointer to a SOMDObject object. 

env (Environment *) 

A pointer to the Environment structure for the method caller, 
ctx (Context) 

A pointer to the Context object of the requested operation, 
operation (Identifier) 

The name of the operation to be performed on the target object, receiver. 
argjist (NVList) 

A pointer to a list of arguments (NVList). If this argument is NULL, the argument list can be assembled by repeated calls to the 
add_arg method on the Request object created by calling this method. 

result (NamedValue) 

A pointer to a NamedValue structure where the result of applying operation to receiver should be stored, 
request (Request) 

A pointer to storage for the address of the created Request object. 
req_flags (Flags) 

A Flags bitmask (unsigned long) that may contain the following flag value: 

OUT_LIST_MEMORY Indicates that any out-arg memory is associated with the argument list. When the list structure is 

freed, any associated out-arg memory is also freed. If OUT_LIST_MEMORY is specified, an 
argument list must also have been specified on the create_request call. 



rc (ORBStatus) 

Returns an ORBStatus value as the status code for the request. 



create_request - Remarks 



The create_request method creates a request to execute a particular operation on the referenced object. For more information on the 
create_request call, see CORBA 1.1 page 109. 

In DSOM, this method is meaningful only when invoked on a SOMDClientProxy object. If invoked on a SOMDObject which is not a client 
proxy, an exception is returned. 



create_request - Original Class 



SOMDObject 




create_request - Related Methods 



Methods 

• create_request_args 

• createjist 

• create_operation_list 



create_request - Example Code 



#include <somd.h> 

#include <repostry.h> 

#include <intfacdf.h> 

#include <foo.h> /* provided by user */ 

/* assume following method declaration in interface Foo : 

* long methodLong (in long inLong, inout long inoutLong) ; 

* then the following code builds a request to execute the call: 

* result = methodLong (fooObj, &ev, 100,200); 

*using the DI I . 

*/ 

Environment ev; 

OperationDef opdef; 

Description desc; 

OperationDescription *opdesc; 

NVList arglist; 
long rc; 

long valuel = 100; 
long value2 = 200; 

Foo fooObj; 

Request reqObj; 

NamedValue result; 

Identifier name; 

TypeCode tc; 
void * dummy; 
long dummylen; 

Flags flags; 

/* Get the OperationDef from the Interface Repository. */ 
opdef = _lookup_id (SOM_Interf aceRepository, 

&ev, "Foo: : methodLong" ) ; 

/* Create a NamedValue list for the operation. */ 
rc= _create_operation_list 

(SOMD_ORBOb ject , &ev, opdef, &arglist) ; 

/* Insert argl info into arglist */ 

_get_item (arglist , &ev, 

0, &name, &tc, &dummy, &dummylen, sflags) ; 

_set_item (arglist, &ev, 0, name, tc, Svaluel, sizeof (long) , flags); 

/* Insert arg2 info into arglist */ 

_get_item (arglist , &ev, 

1, &name, &tc, &dummy, &dummylen, sflags) ; 

_set_item (arglist , &ev, 1 , name, tc, &value2, sizeof (long) , flags); 

/* Get the operation description structure. */ 
desc = _describe (opdef , &ev) ; 

opdesc = (OperationDescription *) desc . value ._value; 

/* Fill in the TypeCode field for result. */ 
result . argument ._type = opdesc->result ; 




/* Finally, create the Request, reqObj */ 

rc = _create_request ( f ooOb j , Sev, (Context *)NULL, "methodLong" , 

arglist, Sresult, SreqObj, (Flags) 0) 



create_request - Topics 



Select an item: 
Syntax 
Parameters 
Returns 
Remarks 
Original Class 
Example Code 
Related Methods 
Glossary 



create_request_args 



create_request_args - Syntax 



This method creates an argument list appropriate for the specified operation. 



SOMDObject 

Environment 

Identifier 

NVList 

NamedValue 

ORBStatus 



receiver; 

*env; 

operation; 
arg_list ; 
result; 
rc; 



rc = create_request_args (receiver, env, 
operation, arg_list, result) ; 



create_request_args Parameter - receiver 



receiver (SOMDObject) 

A pointer to the SOMDObject object to create the request. 



create_request_args Parameter - env 



env (Environment *) 

A pointer to the Environment structure for the method caller. 



create_request_args Parameter - operation 



operation (Identifier) 

The Identifier of the operation for which the argument list is being created. 



create_request_args Parameter - argjist 



argjist (NVList) 

A pointer to the location where the method will store a pointer to the resulting argument list. 



create_request_args Parameter - result 



result (NamedValue) 

A pointer to the NamedValue structure which will be used to hold the result. The result's type field is filled in with the TypeCode of 
the expected result. 



create_request_args Parameter - rc 



rc (ORBStatus) 

Returns an ORBStatus value representing the return code of the request. 



create_request_args - Parameters 



receiver (SOMDObject) 

A pointer to the SOMDObject object to create the request, 
env (Environment *) 

A pointer to the Environment structure for the method caller. 



operation (Identifier) 




The Identifier of the operation for which the argument list is being created. 



argjist (NVList) 

A pointer to the location where the method will store a pointer to the resulting argument list, 
result (NamedValue) 

A pointer to the NamedValue structure which will be used to hold the result. The resu/t ' s type field is filled in with the TypeCode of 
the expected result. 

rc (ORBStatus) 

Returns an ORBStatus value representing the return code of the request. 



create_request_args - Remarks 



The create_request_args method creates the appropriate arg_//st (NVList) for the specified operation. It is similar in function to the 
create_operation_list method. Its value is that it also creates the result structure whereas create_operation_list does not. 

In DSOM, this method is meaningful only when invoked on a SOMDClientProxy object. If invoked on a SOMDObject which is not a client 
proxy, an exception is returned. 



create_request_args - Original Class 

SOMDObject 



create_request_args - Related Methods 



Methods 



duplicate 

release 

create_request 

create_operation_list 



create_request_args - Example Code 



#include 

#include 

#include 

#include 



<somd . h> 
crepostry . h> 
cintf acdf . h> 

<foo.h> /* provided by user */ 



/* assume following method declaration in interface Foo : 

* long methodLong (in long inLong, inout long inoutLong) ; 

* then the following code builds a request to execute the call: 

* result = methodLong (fooObj, &ev, 100,200); 

* using the DI I . 

*/ 



Environment ev; 




OperationDef opdef; 

Description desc; 

OperationDescription *opdesc; 

NVList arglist; 
long rc; 

long valuel = 100; 
long value2 = 200; 

Foo fooObj; 

Request reqObj; 

NamedValue result; 

Identifier name; 

TypeCode tc; 
void * dummy; 
long dummylen; 

Flags flags; 

/* Get the OperationDef from the Interface Repository. */ 
opdef = _lookup_id (SOM_Interf aceRepository, 

&ev, "Foo: :methodLong" ) ; 

/* Create a NamedValue list for the operation. */ 
rc= _create_request_args ( fooObj , &ev, 

"methodLong" , &arglist, &result) ; 



/* Insert argl info into arglist */ 

_get_item (arglist , &ev, 

0, &name, &tc, &dummy, &dummylen, sflags) ; 

_set_item (arglist, &ev, 0, name, tc, &valuel, sizeof (long) , flags); 



/* Insert arg2 info into arglist */ 

_get_item (arglist , &ev, 

1, &name, &tc, &dummy, &dummylen, Sflags) ; 

_set_item (arglist , &ev, 1 , name, tc, &value2, sizeof (long) , flags); 



/* Finally, create the Request, reqObj */ 

rc = _create_request (fooObj, &ev, (Context *)NULL, "methodLong" , 

arglist, &result, &reqObj, (Flags) 0) 



create_request_args - Topics 



Select an item: 
Syntax 
Parameters 
Returns 
Remarks 
Original Class 
Example Code 
Related Methods 
Glossary 



duplicate 



duplicate - Syntax 



This method makes a duplicate of an object reference. 



SOMDObject receiver; 

Environment *env; 

SOMDObject rc; 

rc = duplicate (receiver, env) ; 



duplicate Parameter - receiver 



receiver (SOMDObject) 

A pointer to a SOMDObject object. 



duplicate Parameter - env 



env (Environment *) 

A pointer to the Environment structure for the method caller. 



duplicate Parameter - rc 

rc (SOMDObject) 

Returns a SOMDObject that is a duplicate of the receiver. Ownership of the returned object is transferred to the caller. 



duplicate - Parameters 



receiver (SOMDObject) 

A pointer to a SOMDObject object. 

env (Environment *) 

A pointer to the Environment structure for the method caller, 
rc (SOMDObject) 

Returns a SOMDObject that is a duplicate of the receiver. Ownership of the returned object is transferred to the caller. 



duplicate - Remarks 



The duplicate method makes a duplicate of the object reference. The release method should be called to free the object. 



duplicate - Original Class 



SOMDObject 



duplicate - Related Methods 



Methods 

• release 

• create 

• create_constant 

• create_SOM_ref 



duplicate - Example Code 



#include <somd.h> 

Environment ev; 

SOMObject obj; 

SOMDObject objrefl, objref2; 

objrefl = _create_SOM_ref (SOMD_SOMOAOb ject , &ev, obj); 
objref2 = _duplicate (objrefl , &ev) ; 

_release (objref2, &ev) ; 



duplicate - Topics 



Select an item: 
Syntax 
Parameters 
Returns 
Remarks 
Original Class 
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Related Methods 
Glossary 



getjmplementation 



getjmplementation - Syntax 



This method returns the implementation definition for the referenced object. 



SOMDObject receiver; 

Environment *env; 

ImplementationDef rc; 

rc = get_implementation (receiver , env) ; 



getjmplementation Parameter - receiver 



receiver (SOMDObject) 

A pointer to a SOMDObject object. 



getjmplementation Parameter - env 



env (Environment *) 

A pointer to the Environment structure for the method caller. 



getjmplementation Parameter - rc 



rc (ImplementationDef) 

Returns the ImplementationDef object for the rece/Ver. Ownership of the returned object is transferred to the caller. 



getjmplementation - Parameters 



receiver (SOMDObject) 

A pointer to a SOMDObject object. 

env (Environment *) 

A pointer to the Environment structure for the method caller, 
rc (ImplementationDef) 

Returns the ImplementationDef object for the rece/Ver. Ownership of the returned object is transferred to the caller. 



getjmplementation - Remarks 



The getjmplementation method returns the implementation definition object for the referenced object. 



getjmplementation - Original Class 

SOMDObject 



getjmplementation - Related Methods 



Methods 



getjnterface 



getjmplementation - Example Code 



#include <somd.h> 

long flags; 

Environment ev; 

SOMDObject objref; 

ImplementationDef impldef; 

impldef = _get_implementat ion (objref , &ev) ; 
flags = get_impl_f lags (impldef , &ev) ; 



getjmplementation - Topics 



Select an item: 
Syntax 
Parameters 
Returns 
Remarks 
Original Class 
Example Code 
Related Methods 
Glossary 



getjnterface 



getjnterface - Syntax 



This method returns the interface definition object for the referenced object. 



SOMDObject receiver; 

Environment *env; 

InterfaceDef rc; 

rc = get_interf ace (receiver, env) ; 



getjnterface Parameter - receiver 



receiver (SOMDObject) 

A pointer to a SOMDObject object. 



getjnterface Parameter - env 



env (Environment *) 

A pointer to the Environment structure for the method caller. 



getjnterface Parameter - rc 



rc (InterfaceDef) 

Returns a pointer to the InterfaceDef object associated with the reference receiver. Ownership of the InterfaceDef object is passed 
to the caller. 



getjnterface - Parameters 



receiver (SOMDObject) 

A pointer to a SOMDObject object. 



env (Environment *) 

A pointer to the Environment structure for the method caller. 



rc (InterfaceDef) 

Returns a pointer to the InterfaceDef object associated with the reference receiver. Ownership of the InterfaceDef object is passed 
to the caller. 



getjnterface - Remarks 



The getjnterface method returns the interface definition object for the referenced object. 



getjnterface - Original Class 

SOMDObject 



getjnterface - Related Methods 



Methods 



getjmplementation 



getjnterface - Example Code 



#include <somd.h> 

#include <repostry.h> 

#include <intfacdf.h> 

Environment ev; 

SOMDObject objref; 

InterfaceDef intf; 

intf = _get_interf ace (objref , &ev) ; 



getjnterface - Topics 



Select an item: 
Syntax 
Parameters 
Returns 



Remarks 
Original Class 
Example Code 
Related Methods 
Glossary 



is constant 



is_constant - Syntax 



This method tests to see If the object reference is a constant (i.e., its ReferenceData is a constant value associated with the reference). 



SOMDObject receiver; 

Environment *env; 

boolean rc; 

rc = is_constant (receiver, env) ; 



is_constant Parameter - receiver 

receiver (SOMDObject) 

A pointer to a SOMDObject object. 



is constant Parameter - env 



env (Environment *) 

A pointer to the Environment structure for the method caller. 



is constant Parameter - rc 



rc (boolean) 

Returns TRUE if the object reference was generated by create_constant, Otherwise, is_constant returns FALSE. 



is constant - Parameters 



receiver (SOMDObject) 

A pointer to a SOMDObject object. 

env (Environment *) 

A pointer to the Environment structure for the method caller, 
rc (boolean) 

Returns TRUE if the object reference was generated by create_constant, Otherwise, is_constant returns FALSE. 



is constant - Remarks 



The is_constant method tests to see if the object reference was created using the create_constant method in the SOMOA class. 



is constant - Related Methods 



Methods 



create 

create_constant 

is_nil 

is_proxy 

is_SOM_ref 



is_constant - Example Code 



#include <somd.h> 

Environment ev; 
SOMDObject objref; 



/* This code might be part of the code 

* that overrides the somdSOMOb jFromRef method, i.e. 

* in an implementation of a subclass of SOMDServer called 

* myServer 
*/ 



if (_is_constant (objref , &ev) ) 
id = _get_id (objref , &ev) ; 



is_constant - Topics 




Select an item: 
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is nil 



is_nil - Syntax 



This method tests to see if the object reference is nil. 



SOMDObject receiver; 

Environment *env; 

boolean rc; 

rc = is_nil (receiver, env) ; 



is nil Parameter - receiver 



receiver (SOMDObject) 

A pointer to a SOMDObject object. 



is nil Parameter - env 



env (Environment *) 

A pointer to the Environment structure for the method caller. 



is nil Parameter - rc 



rc (boolean) 



Returns TRUE if the object reference is empty. Otherwise, is_nil returns FALSE. 



is nil - Parameters 



receiver (SOMDObject) 

A pointer to a SOMDObject object. 

env (Environment *) 

A pointer to the Environment structure for the method caller, 
rc (boolean) 

Returns TRUE if the object reference is empty. Otherwise, is_nil returns FALSE. 



is nil - Remarks 



The is_nil method tests to see if the specified object reference is nil. 



is nil - Related Methods 



Methods 



create 

is_constant 

is_proxy 

is_SOM_ref 



is_nil - Example Code 



#include <somd.h> 

Environment ev; 

SOMDObject objref; 

SOMObject somobj; 

/* This code might be part of the code 

* that overrides the somdSOMOb jFromRef method, i.e. 

* in an implementation of a subclass of SOMDServer called 

* myServer 
*/ 

if (_is_nil (objref , &ev) &bxv.&bxv. 

_somIsA (objref , SOMDClientProxyNewClass ( 0 , 0)) &bxv.&bxv. 
_is_SOM_ref (objref, &ev) ) { 

somobj = myServer_parent_SOMDServer_somdSOMOb jFromRef 
(somSelf , &ev, objref) ; 



else { 

/* do the myServer-specif ic stuff to create/find somobj here */ 




return somobj; 



is_nil - Topics 
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is_proxy 



is_proxy - Syntax 



This method tests to see if the object reference is a proxy. 



rc = is_proxy (receiver, env) ; 



is_proxy Parameter - receiver 



receiver (SOMDObject) 

A pointer to a SOMDObject object. 



is_proxy Parameter - env 



env (Environment *) 

A pointer to the Environment structure for the method caller. 



SOMDObject 

Environment 

boolean 



receiver; 

*env; 

rc; 



is_proxy Parameter - rc 



rc (boolean) 

Returns TRUE if the object reference is a proxy object. Otherwise, is_proxy returns FALSE. 



is_proxy - Parameters 



receiver (SOMDObject) 

A pointer to a SOMDObject object. 

env (Environment *) 

A pointer to the Environment structure for the method caller, 
rc (boolean) 

Returns TRUE if the object reference is a proxy object. Otherwise, is_proxy returns FALSE. 



is_proxy - Remarks 



The is_proxy method tests to see if the specified object reference is a proxy object. 



is_proxy - Original Class 



SOMDObject 



is_proxy - Related Methods 



Methods 

• is_nil 

• is_constant 

• is_SOM_ref 

• string_to_object 



is_proxy - Example Code 




#include <somd.h> 



SOMDObject objref; 

Environment ev; 

Context ctx; 

NVlist arglist; 

NamedValue result; 

Request reqObj; 

if (_is_proxy (objref , Sev) ) { 

/* create a remote request for target object */ 

rc = _create_request (ob j , Sev, ctx, 

"testMethod" , arglist, Sresult, SreqObj, 
(Flags) 0) ; 



is_proxy - Topics 
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Example Code 
Related Methods 
Glossary 



is SOM ref 



is_SOM_ref - Syntax 



This method tests to see if the object reference is a simple reference to a SOM object. 



SOMDObject 

Environment 

boolean 



receiver; 

*env; 

rc; 



rc = is_SOM_ref (receiver, env) ; 



is SOM ref Parameter - receiver 



receiver (SOMDObject) 

A pointer to a SOMDObject object. 



is SOM ref Parameter - env 



env (Environment *) 

A pointer to the Environment structure for the method caller. 



is SOM ref Parameter - rc 



rc (boolean) 

Returns TRUE if the object reference is a simple (transient) reference to a SOM object. Otherwise, is_SOM_ref returns FALSE. 



is SOM ref - Parameters 



receiver (SOMDObject) 

A pointer to a SOMDObject object. 

env (Environment *) 

A pointer to the Environment structure for the method caller, 
rc (boolean) 

Returns TRUE if the object reference is a simple (transient) reference to a SOM object. Otherwise, is_SOM_ref returns FALSE. 



is SOM ref - Remarks 



The is_SOM_ref method tests to see if the specified object reference is a simple (transient) reference to a SOM object. 



is_SOM_ref - Original Class 

SOMDObject 



is SOM ref - Related Methods 



Methods 




• create_SOM_ref 

• getSOMobject 

• is_proxy 

• is_nil 

• is_constant 



is_SOM_ref - Example Code 



#include <somd.h> 

SOMDObject objref; 

Environment ev; 

SOMObject obj; 

if (_is_SOM_ref (objref, &ev) ) 

/* we know objref is a simple reference, so we can ... */ 
obj = _get_SOM_ob ject (SOMD_SOMOAOb ject , &ev, objref); 



is_SOM_ref - Topics 



Select an item: 
Syntax 
Parameters 
Returns 
Remarks 
Original Class 
Example Code 
Related Methods 
Glossary 



release 



release - Syntax 



This method releases the memory associated with the specified object reference. 



SOMDObject receiver; 

Environment *env; 



release (receiver, env) ; 



release Parameter - receiver 



receiver (SOMDObject) 

A pointer to a SOMDObject object. 



release Parameter - env 



env (Environment *) 

A pointer to the Environment structure for the method caller. 



release Parameter - rc 



rc 



release - Parameters 



receiver (SOMDObject) 

A pointer to a SOMDObject object. 

env (Environment *) 

A pointer to the Environment structure for the method caller. 



rc 



release - Remarks 



The release method releases the memory associated with the object reference. 



release - Original Class 




SOMDObject 



release - Related Methods 



Methods 



• duplicate 

• somdReleaseObject 

• somdReleaseResources 

• somdProxyFree 

• create 

• create_constant 

• create_SOM_ref 



release - Example Code 



#include <somd.h> 

SOMDObject objref; 

Environment ev; 

SOMObject obj; 

objref = _create_SOM_ref (SOMD_SOMOAObject, Sev, obj); 
_release (objref , Sev); 



release - Topics 



Select an item: 
Syntax 
Parameters 
Returns 
Remarks 
Original Class 
Example Code 
Related Methods 
Glossary 



SOMDObjectMgr 



File stem: somdom 



Base 



ObjectMgr 

Metaclass 

SOMMSinglelnstance 

Ancestor Classes 
ObjectMgr 

SOMObject 

Description 

The SOMDObjectMgr class is derived from ObjectMgr class and provides the DSOM implementations for the ObjectMgr methods. 
Attributes 

Listed below is an available SOMDObjectMgr attribute, with its corresponding type in parentheses, followed by a description of its purpose: 

somd21somFree (boolean) 

Determines whether or not somFree, when invoked on a proxy object, will free the proxy object along with the remote object. The 
default value is FALSE, indicating that only the remote object will be freed when somFree is invoked on a proxy object. Setting this 
attribute to TRUE as part of client-program initialization, for example, 

set_somd2 lsomdFree (SOMD_Ob jectMgr , ev, TRUE); 

has the effect that all subsequent invocations of somFree on proxy objects will free both the remote object and the proxy. 

New methods 

The following list shows all the SOMDObjectMgr methods. 

• somdFindAnyServerByClass* 

• somdFindServer* 

■ somdFindServersByClass* 

• somdFindServerByName* 

(* This class and its methods were added by DSOM to supplement the published CORBA 1 .1 interfaces.) 

Overridden methods 

The following list shows all the methods overridden by the SOMDObjectMgr class. These methods are overridden in order to modify the 
behavior defined by an ancestor class. 

• somdDestroyObject 

• somdGetldFromObject 

• somdGetObjectFromld 

• somdNewObject 

• somdReleaseObject 

• somlnit 



somdFindAnyServerByClass 



somdFindAnyServerByClass - Syntax 



This method finds a server capable of creating the specified object. 



SOMDObjectMgr 

Environment 



receiver; 

env; 



Identifier 

SOMDServer 



objclass; 

rc; 



rc = somdFindAnyServerByClass (receiver, env, 
objclass) ; 



somdFindAnyServerByClass Parameter - receiver 



receiver (SOMDObjectMgr) 

A pointer to a SOMDObjectMgr object. 



somdFindAnyServerByClass Parameter - env 



env (Environment *) 

A pointer to the Environment structure for the method caller. 



somdFindAnyServerByClass Parameter - objclass 



objclass (Identifier) 

An Identifier specifying the class of the object the server needs to be able to create. 



somdFindAnyServerByClass Parameter - rc 



rc (SOMDServer) 

Returns a pointer to a SOMDServer proxy. If no server can be found in the Implementation Repository that implements the specified 
class, NULL is returned. 



somdFindAnyServerByClass - Parameters 



receiver (SOMDObjectMgr) 

A pointer to a SOMDObjectMgr object. 



env (Environment *) 

A pointer to the Environment structure for the method caller. 



objclass (Identifier) 



An Identifier specifying the class of the object the server needs to be able to create, 
rc (SOMDServer) 

Returns a pointer to a SOMDServer proxy. If no server can be found in the Implementation Repository that implements the specified 
class, NULL is returned. 



somdFindAnyServerByClass - Remarks 



The somdFindAnyServerByClass method finds a server capable of creating an object of the specified type with the specified properties. 



somdFindAnyServerByClass - Original Class 



SOMDObjectMgr 



somdFindAnyServerByClass - Related Methods 



Methods 



SomdFindServersByClass 

somdFindServer 

somdFindServerByName 



somdFindAnyServerByClass - Example Code 



#include <somd.h> 

#include <stack.h> /* provided by user */ 

Stack stk; 

Environment ev; 

SOMDServer server; 

SOM_InitEnvironment (&ev) ; 

SOMD_Init (&ev) ; 

StackNewClass (0,0) ; 
server = 

_somdFindAnyServerByClass (SOMD_Ob jectMgr , &ev, "Stack"); 
stk = _somdCreateObj (server, &ev, "Stack", ""); 

_somdDestroyOb ject (SOMD_Ob jectMgr , &ev, stk) ; 



somdFindAnyServerByClass - Topics 




Select an item: 
Syntax 
Parameters 
Returns 
Remarks 
Original Class 
Example Code 
Related Methods 
Glossary 



somdFindServer 



somdFindServer - Syntax 



This method finds a server, given its ImplementationDef ID. 



SOMDOb jectMgr 
Environment 
Implld 
SOMDServer 



receiver; 

*env; 

serverid; 

rc; 



rc = somdFindServer (receiver, env, serverid); 



somdFindServer Parameter - receiver 



receiver (SOMDObjectMgr) 

A pointer to a SOMDObjectMgr object. 



somdFindServer Parameter - env 



env (Environment *) 

A pointer to the Environment structure for the method caller. 



somdFindServer Parameter - serverid 



serverid (Implld) 

An Implld string which identifies the ImplementationDef of the desired server. 



somdFindServer Parameter - rc 



rc (SOMDServer) 

Returns a pointer to a SOMDServer proxy. 



somdFindServer - Parameters 



receiver (SOMDObjectMgr) 

A pointer to a SOMDObjectMgr object. 

env (Environment *) 

A pointer to the Environment structure for the method caller, 
serverid (Implld) 

An Implld string which identifies the ImplementationDef of the desired server, 
rc (SOMDServer) 

Returns a pointer to a SOMDServer proxy. 



somdFindServer - Remarks 



The somdFindServerByName method finds a server capable of creating an object of the specified type with the specified properties. 



somdFindServer - Original Class 



SOMDObjectMgr 



somdFindServer - Related Methods 



Methods 



somdFindServerByName 

somdFindServersByClass 

somdAnyFindServerByClass 




somdFindServer - Example Code 



#include <somd.h> 

#include <stack.h> /* provided by user */ 

Stack stk; 

Environment ev; 

SOMDServer server; 

Implld implid; 

SOM_InitEnvironment (&ev) ; 

SOMD_Init (&ev) ; 

StackNewClass (0,0); 

server = ^somdFindServer ( SOMD_Ob jectMgr, &ev, implid); 
stk = _somdCreateObj (server, &ev, "Stack", ""); 

_somdDestroyOb ject (SOMD_Ob jectMgr, &ev, stk) ; 



somdFindServer - Topics 



Select an item: 
Syntax 
Parameters 
Returns 
Remarks 
Original Class 
Example Code 
Related Methods 
Glossary 



somdFindServerByName 



somdFindServerByName - Syntax 



This method finds a server given its ImplementationDef name (alias). 



SOMDOb jectMgr 
Environment 
string 
SOMDServer 



receiver; 

*env; 

servername ; 
rc; 



rc = somdFindServerByName (receiver, env, servername) ; 



somdFindServerByName Parameter - receiver 



receiver (SOMDObjectMgr) 

A pointer to a SOMDObjectMgr object. 



somdFindServerByName Parameter - env 



env (Environment *) 

A pointer to the Environment structure for the method caller. 



somdFindServerByName Parameter - servername 



servername (string) 

A string which specifies the name of the ImplementationDef of the desired server. 



somdFindServerByName Parameter - rc 



rc (SOMDServer) 

Returns a pointer to a SOMDServer proxy. 



somdFindServerByName - Parameters 



receiver (SOMDObjectMgr) 

A pointer to a SOMDObjectMgr object. 

env (Environment *) 

A pointer to the Environment structure for the method caller. 

servername (string) 

A string which specifies the name of the ImplementationDef of the desired server, 
rc (SOMDServer) 

Returns a pointer to a SOMDServer proxy. 



somdFindServerByName - Remarks 




The somdFindServerByName method finds a server with the specified name. 



somdFindServerByName - Original Class 



SOMDObjectMgr 



somdFindServerByName - Related Methods 



Methods 



somdFindServer 

somdFindServersByClass 

somdAnyFindServerByClass 



somdFindServerByName - Example Code 



#include <somd.h> 

#include <stack.h> /* provided by user */ 

Stack stk; 

Environment ev; 

SOMDServer server; 

SOM_InitEnvironment (&ev) ; 

SOMD_Init (&ev) ; 

StackNewClass (0,0); 
server = 

_somdFindServerByName (SOMD_Ob jectMgr , &ev, "stackServer") ; 
stk = _somdCreateObj (server, &ev, "Stack", ""); 

_somdDestroyOb ject (SOMD_Ob jectMgr , &ev, stk) ; 



somdFindServerByName - Topics 



Select an item: 
Syntax 
Parameters 
Returns 
Remarks 
Original Class 
Example Code 
Related Methods 
Glossary 



somdFindServersByClass 



somdFindServersByClass - Syntax 



This method finds all servers capable of creating a particular object. 



SOMDOb jectMgr 

Environment 

Identifier 

sequence<SOMDServer> 



receiver; 

*env; 

objclass; 

rc; 

env, 



rc = somdFindServersByClass (receiver, 
objclass) ; 



somdFindServersByClass Parameter - receiver 



receiver (SOMDObjectMgr) 

A pointer to a SOMDObjectMgr object. 



somdFindServersByClass Parameter - env 



env (Environment *) 

A pointer to the Environment structure for the method caller. 



somdFindServersByClass Parameter - objclass 



objclass (Identifier) 

An Identifier representing the type of the object the server needs to be able to create. 



somdFindServersByClass Parameter - rc 



rc (sequence<SOMDServer>) 

Returns a sequence of SOMDServer objects capable of creating the specified object. 



somdFindServersByClass - Parameters 



receiver (SOMDObjectMgr) 

A pointer to a SOMDObjectMgr object. 

env (Environment *) 

A pointer to the Environment structure for the method caller, 
objclass (Identifier) 

An Identifier representing the type of the object the server needs to be able to create, 
rc (sequence<SOMDServer>) 

Returns a sequence of SOMDServer objects capable of creating the specified object. 



somdFindServersByClass - Remarks 



The somdFindServersByClass method finds all servers capable of creating a particular object with the specified properties. 



somdFindServersByClass - Original Class 



SOMDObjectMgr 



somdFindServersByClass - Related Methods 



Methods 



somdFindServer 

somdFindServerByName 

somdFindAnyServerByClass 



somdFindServersByClass - Example Code 



#include <somd.h> 

#include <stack.h> /* provided by user */ 



Stack stk; 
Environment ev; 




sequence (SOMDServer) servers; 

SOMDServer server; 

SOMDServer chooseServer (sequence (SOMDServer) servers); 

SOM_InitEnvironment (&ev) ; 

SOMD_Init (&ev) ; 

StackNewClass (0,0); 

servers = _somdFindServersByClass (SOMD_Ob jectMgr, &ev, "Stack"); 
server = chooseServer (servers) ; 

stk = _somdCreateObj (server, &ev, "Stack", ""); 

_somdDestroyOb ject (SOMD_Ob jectMgr, &ev, stk) ; 



somdFindServersByClass - Topics 



Select an item: 
Syntax 
Parameters 
Returns 
Remarks 
Original Class 
Example Code 
Related Methods 
Glossary 



SOMDServer 



File stem: SOMDServer 

Base 

SOMObject 

Metaclass 

SOMMSinglelnstance 

Ancestor Classes 
SOMObject 

Description 

The SOMDServer class is a base class that defines and implements methods for managing objects in a DSOM server process. This 
includes methods for the creation and deletion of SOM objects, and for getting the SOM class object for a specified class. The SOMDServer 
class also defines and implements methods for the mapping between object references (SOMDObjects) and SOM objects, and dispatching 
methods on objects. 

Application-specific methods for managing application objects can be introduced in subclasses of SOMDServer. 

New methods 

The following list shows all the SOMDServer methods. 

• somdCreateObj* 

• somdDeleteObj* 

• somdDispatchMethod* 

• somdGetClassObj* 

• somdObjReferencesCached* 

• somdRefFromSOMObj* 

• somdSOMObjFromRef* 



(* This class and its methods were added by DSOM to supplement the published CORBA 1 .1 interfaces.) 



somdCreateObj 



somdCreateObj - Syntax 



This method creates an object of the specified class. 



SOMDServer 

Environment 

Identifier 

string 

SOMObject 



receiver; 

*env; 

objclass; 

hints; 

rc; 



rc = somdCreateObj (receiver, env, objclass, 
hints) ; 



somdCreateObj Parameter - receiver 



receiver (SOMDServer) 

A pointer to a SOMDServer object capable of creating a instance of the specified class. 



somdCreateObj Parameter - env 



env (Environment *) 

A pointer to the Environment structure for the method caller. 



somdCreateObj Parameter - objclass 



objclass (Identifier) 

The class of the object for which an instance is to be created. 



somdCreateObj Parameter - hints 



hints (string) 

A string which may optionally be used to specify special creation options. 



somdCreateObj Parameter - rc 



rc (SOMObject) 

Returns a SOMObject of the class specified by objc/ass. 



somdCreateObj - Parameters 



receiver (SOMDServer) 

A pointer to a SOMDServer object capable of creating a instance of the specified class, 
env (Environment *) 

A pointer to the Environment structure for the method caller, 
objclass (Identifier) 

The class of the object for which an instance is to be created, 
hints (string) 

A string which may optionally be used to specify special creation options, 
rc (SOMObject) 

Returns a SOMObject of the class specified by objc/ass. 



somdCreateObj - Remarks 



The somdCreateObj method creates an object of the specified class. 



somdCreateObj - Original Class 

SOMDServer 



somdCreateObj - Example Code 



#include <somd.h> 

#include <stack.h> /* provided by user */ 




Stack stk; 

Environment ev; 

SOMDServer server; 

SOM_InitEnvironment (&ev) ; 

SOMD_Init (&ev) ; 

StackNewClass (0,0); 
server = 

_somdFindServerByName (SOMD_Ob jectMgr, &ev, "stackServer") ; 
stk = _somdCreateObj (server, &ev, "Stack", ""); 

_somdDestroyOb ject (SOMD_Ob jectMgr, &ev, stk) ; 



somdCreateObj - Topics 



Select an item: 
Syntax 
Parameters 
Returns 
Remarks 
Original Class 
Example Code 
Glossary 



somdDeleteObj 



somdDeleteObj - Syntax 



This method deletes the specified object. 



SOMDServer 

Environment 

SOMObject 



receiver; 
*env; 
somob j ; 



somdDeleteObj (receiver, env, somobj); 



somdDeleteObj Parameter - receiver 



receiver (SOMDServer) 

A pointer to a SOMDServer object. 



somdDeleteObj Parameter - env 



env (Environment *) 

A pointer to the Environment structure for the method caller. 



somdDeleteObj Parameter - somobj 



somobj (SOMObject) 

An object "managed" by the server object. 



somdDeleteObj Parameter - rc 



rc 



somdDeleteObj - Parameters 



receiver (SOMDServer) 

A pointer to a SOMDServer object. 

env (Environment *) 

A pointer to the Environment structure for the method caller. 

somobj (SOMObject) 

An object "managed" by the server object. 



rc 



somdDeleteObj - Remarks 



The somdDeleteObj method deletes the specified object. 



somdDeleteObj - Original Class 




SOMDServer 



somdDeleteObj - Example Code 



#include <somd.h> 

#include <stack.h> /* provided by user */ 

Stack stk; 

Environment ev; 

SOMDServer server; 

SOM_InitEnvironment (&ev) ; 

SOMD_Init (&ev) ; 

StackNewClass (0,0); 
server = 

_somdFindServerByName (SOMD_Ob jectMgr, &ev, "stackServer") 
stk = _somdCreateObj (server, &ev, "Stack", ""); 

_somdDeleteOb j (server, &ev, stk) ; 



somdDeleteObj - Topics 



Select an item: 
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Parameters 
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Remarks 
Original Class 
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somdDispatchMethod 



somdDispatchMethod - Syntax 



This method dispatches a method on the specified SOM object. 



SOMDServer 

Environment 

SOMObject 

somToken 

somld 

va_list 



receiver; 
*env; 
somob j ; 
retValue; 
methodld; 
ap; 



somdDispatchMethod (receiver , env, somobj, 
retValue, methodld, ap) ; 



somdDispatchMethod Parameter - receiver 



receiver (SOMDServer) 

A pointer to a SOMDServer object. 



somdDispatchMethod Parameter - env 



env (Environment *) 

A pointer to the Environment structure for the method caller. 



somdDispatchMethod Parameter - somobj 



somobj (SOMObject) 

A pointer to an object "managed" by the server object. 



somdDispatchMethod Parameter - retValue 



retValue (somToken) 

A pointer to the storage area allocated to hold the method result value, if any. 



somdDispatchMethod Parameter - methodld 



methodld (somld) 

A somld for the name of the method which is to be dispatched. 



somdDispatchMethod Parameter - ap 




ap (vajist) 

A pointer to a vajist array of arguments to the method call. 



somd Dispatch Method Parameter - rc 



rc 

Returns a result, if any, in the storage whose address is in retVa/ue. 



somdDispatchMethod - Parameters 



receiver (SOMDServer) 

A pointer to a SOMDServer object. 

env (Environment *) 

A pointer to the Environment structure for the method caller, 
somobj (SOMObject) 

A pointer to an object "managed" by the server object. 
retValue (somToken) 

A pointer to the storage area allocated to hold the method result value, if any. 
methodic! (somld) 

A somld for the name of the method which is to be dispatched, 
ap (vajist) 

A pointer to a vajist array of arguments to the method call. 



rc 

Returns a result, if any, in the storage whose address is in retVa/ue. 



somdDispatchMethod - Remarks 



The somdDispatchMethod method is used to intercept method calls on objects in a server. When a request arrives, the request 
parameters are extracted from the message, and the target object is resolved. Then, the SOMOA dispatches the method call on the target 
object using the somdDispatchMethod method. 

The default implementation will call somDispatch on the target object with the parameters as specified. This method can be overridden to 
intercept and process the method calls before they are dispatched. 



somdDispatchMethod - Original Class 



SOMDServer 




somd Dispatch Method - Example Code 



#include <somd.h> 

/* overridden somdDispatchMethod */ 

void somdDispatchMethod (SOMD Server *somself, Environment *ev, 

SOMObject *somobj, somToken *retValue, 
somld methodld, va_list ap) 

{ 

printf ( "dispatching %s on %x\n", SOM_StringFromId (methodld) , 
somob j ) ; 

SOMOb ject_somDispatch (somob j , ev, retValue, methodld, ap) ; 

} 



somdDispatchMethod - Topics 



Select an item: 
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Parameters 
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Remarks 
Original Class 
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Glossary 



somdGetClassObj 



somdGetClassObj - Syntax 



This method creates a class object for the specified class. 



SOMDServer 

Environment 

Identifier 

SOMClass 



receiver; 
*env; 
ob jclass; 
rc; 



rc = somdGetClassObj (receiver, env, objclass) ; 



somdGetClassObj Parameter - receiver 



receiver (SOMDServer) 

A pointer to a SOMDServer object. 



somdGetClassObj Parameter - env 



env (Environment *) 

A pointer to the Environment structure for the method caller. 



somdGetClassObj Parameter - objclass 



objclass (Identifier) 

An identifier specifying the type of the class object to be created. 



somdGetClassObj Parameter - rc 



rc (SOMCIass) 

Returns a SOMCIass object of the type specified. 



somdGetClassObj - Parameters 



receiver (SOMDServer) 

A pointer to a SOMDServer object. 

env (Environment *) 

A pointer to the Environment structure for the method caller, 
objclass (Identifier) 

An identifier specifying the type of the class object to be created, 
rc (SOMCIass) 

Returns a SOMCIass object of the type specified. 



somdGetClassObj - Remarks 



The somdGetClassObj method creates a class object of the specified type. 




somdGetClassObj - Original Class 

SOMDServer 



somdGetClassObj - Example Code 



#include <somd.h> 

#include <stack.h> /* provided by user */ 

SOMClass stkclass; 

Environment ev; 

SOMDServer server; 

SOM_InitEnvironment (&ev) ; 

SOMD_Init (&ev) ; 

StackNewClass (0,0); 
server = 

_somdFindServerByName (SOMD_Ob jectMgr , &ev, "stackServer") ; 
stkclass = _somdGetClassObj (server, &ev, "Stack", ""); 



somdGetClassObj - Topics 



Select an item: 
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Parameters 
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Original Class 
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somdObjReferencesCached 



somdObjReferencesCached - Syntax 



This method indicates whether a server object retains ownership of the object references it creates via the somdRefFromSOMObj method. 



SOMDServer 

Environment 

boolean 



receiver; 

env; 

rc; 



rc = somdOb jReferencesCached (receiver , env) ; 



somdObjReferencesCached Parameter - receiver 



receiver (SOMDServer) 

A pointer to an object of class SOMDServer. 



somdObjReferencesCached Parameter - env 



env (Environment *) 

A pointer to the Environment structure for the calling method. 



somdObjReferencesCached Parameter - rc 



rc (boolean) 



FALSE Returns FALSE by default. 

TRUE Overriding implementations may return TRUE to indicate that a subclass of SOMDServer 

implements object reference caching. 



somdObjReferencesCached - Parameters 



receiver (SOMDServer) 

A pointer to an object of class SOMDServer. 

env (Environment *) 

A pointer to the Environment structure for the calling method, 
rc (boolean) 



FALSE Returns FALSE by default. 

TRUE Overriding implementations may return TRUE to indicate that a subclass of SOMDServer 

implements object reference caching. 



somdObjReferencesCached - Remarks 




This method indicates whether a server object retains ownership of the object references it creates via the somdRefFromSOMObj method. 
The default implementation returns FALSE, meaning that the server turns over ownership of the object references it creates to the caller. 
Subclasses of SOMDServer that implement object reference caching should override this method to return TRUE. 



somdObjReferencesCached - Original Class 



SOMDServer 



somdObjReferencesCached - Related Methods 



Methods 



somdRefFromSOMObj 



somdObjReferencesCached - Example Code 



SOMDobject objref; 

objref = _somdRef FromSOMOb j ( serverOb j , ev, myobj) ; 
/* code to use objref */ 

if ( !_somdOb jRef erencesCached ( serverOb j , ev) ) 
_release (objref, ev) ; 



somdObjReferencesCached - Topics 



Select an item: 
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somdRefFromSOMObj 



somdRefFromSOMObj - Syntax 



This method returns an object reference corresponding to the specified SOM object. 



SOMDServer 

Environment 

SOMObject 

SOMDObject 



receiver; 
*env; 
somobj ; 
rc; 



rc = somdRefFromSOMObj (receiver , env, somob j) ; 



somdRefFromSOMObj Parameter - receiver 



receiver (SOMDServer) 

A pointer to a SOMDServer object. 



somdRefFromSOMObj Parameter - env 



env (Environment *) 

A pointer to the Environment structure for the method caller. 



somdRefFromSOMObj Parameter - somobj 



somobj (SOMObject) 

A pointer to the SOM object for which a DSOM reference is to be created. 



somdRefFromSOMObj Parameter - rc 



rc (SOMDObject) 

Returns a DSOM reference (that is, a SOMDObject) for the SOM object specified. 



somdRefFromSOMObj - Parameters 



receiver (SOMDServer) 

A pointer to a SOMDServer object. 

env (Environment *) 

A pointer to the Environment structure for the method caller, 
somobj (SOMObject) 

A pointer to the SOM object for which a DSOM reference is to be created, 
rc (SOMDObject) 

Returns a DSOM reference (that is, a SOMDObject) for the SOM object specified. 



somdRefFromSOMObj - Remarks 



The somdRefFromSOMObj method creates a simple (transient) reference to a SOM object. This method is called by SOMOA as part of 
converting the results of a local method call into a result message for a remote client. 

By default the somdRefFromSOMObj method turns over ownership of the object reference it creates to the caller. However, if a subclass of 
SOMDServer overrides somdRefFromSOMObj to implement object reference caching, then that subclass should also override the method 
somdObjReferencesCached to report that caching by returning TRUE. 



somdRefFromSOMObj - Original Class 

SOMDServer 



somdRefFromSOMObj - Related Methods 



Methods 



somdObjReferencesCached 



somdRefFromSOMObj - Example Code 



#include <somd.h> 

#include <stack.ih> /* user-generated */ 

SOMDObject objref; 

Environment ev; 

SOMObject obj; 

/* myServer specific code up here */ 

/* one might want to make this call as part of the code 

* that overrides the somdRefFromSOMObj method, i.e. 

* in an implementation of a subclass of SOMDServer called 




myServer 



*/ 

objref = 

myServer_parent_SOMDServer_somdRefFromSOMOb j ( somSelf , &ev, obj); 



somdRefFromSOMObj - Topics 



Select an item: 
Syntax 
Parameters 
Returns 
Remarks 
Original Class 
Example Code 
Related Methods 
Glossary 



somdSOMObj From Ref 



somdSOMObj From Ref - Syntax 



This method returns the SOM object corresponding to the specified object reference. 



SOMDServer 

Environment 

SOMDObject 

SOMObject 



receiver; 

*env; 

objref; 

rc; 



rc = somdSOMOb jFromRef (receiver, env, objref) ; 



somdSOMObj From Ref Parameter - receiver 



receiver (SOMDServer) 

A pointer to a SOMDServer object. 



somdSOMObjFromRef Parameter - env 



env (Environment *) 

A pointer to the Environment structure for the method caller. 



somdSOMObj From Ref Parameter - objref 



objref (SOMDObject) 

A pointer to the DSOM object reference to the SOM object. 



somdSOMObj From Ref Parameter - rc 



rc (SOMObject) 

Returns the SOM object associated with the supplied DSOM reference. 



somdSOMObjFromRef - Parameters 



receiver (SOMDServer) 

A pointer to a SOMDServer object. 

env (Environment *) 

A pointer to the Environment structure for the method caller, 
objref (SOMDObject) 

A pointer to the DSOM object reference to the SOM object, 
rc (SOMObject) 

Returns the SOM object associated with the supplied DSOM reference. 



somdSOMObjFromRef - Remarks 



The somdSOMObjFromRef method returns the SOM object associated with the DSOM object reference, objref. This method is called by 
SOMOA as part of converting a remote request into a local method call on an object. 



somdSOMObjFromRef - Original Class 



SOMDServer 



somdSOMObjFromRef - Example Code 




#include <somd.h> 

#include <stack.ih> /* user-generated */ 

SOMDObject objref; 

Environment ev; 

SOMObject obj; 

/* myServer specific code up here */ 

/* one might want to make this call as part of the code 

* that overrides the somdRefFromSOMOb j method, i.e. 

* in an implementation of a subclass of SOMDServer called 

* myServer 
*/ 

obj = 

myServer_parent_SOMDServer_somdSOMOb jFromRef (somSelf , &ev, objref) ; 



somdSOMObj From Ref - Topics 



Select an item: 
Syntax 
Parameters 
Returns 
Remarks 
Original Class 
Example Code 
Glossary 



SOMDServerMgr 



File stem: servmgr 
Base 

SOMObject 

Metaclass 

SOMCIass 

Ancestor Classes SOMOBject 
Description 

The SOMDServerMgr class provides a programmatic interface to manager server processes. At present, the server processes that can be 
managed are limited to those present in the Implementation Repository. The choice of Implementation Repository is determined by the 
environment variable SOMDDIR. 

New methods 

The following list shows all the SOMDServerMgr methods. 

• somdDisableServer 

■ somdEnableServer 

• somdlsServerEnabled 

■ somdListServer 



somdRestartServer 

somdShutdownServer 

somdStartServer 



somdDisableServer 



somdDisableServer - Syntax 



This method disables a server process from starting until it is explicitly enabled again. 



SOMDServerMgr 

Environment 

string 

ORBStatus 



receiver; 

*env; 

server_alias ; 
rc; 



rc = somdDisableServer (receiver, env, server_alias) ; 



somdDisableServer Parameter - receiver 



receiver (SOMDServerMgr) 

A pointer to an object of class SOMDServerMgr. 



somdDisableServer Parameter - env 



env (Environment *) 

A pointer to the Environment structure for the calling method. 



somdDisableServer Parameter - server alias 



server alias (string) 

The implementation alias of the server to be disabled. 



somdDisableServer Parameter - rc 



rc (ORBStatus) 

Returns 0 for success or a DSOM error code for failure. 



somdDisableServer - Parameters 



receiver (SOMDServerMgr) 

A pointer to an object of class SOMDServerMgr. 

env (Environment *) 

A pointer to the Environment structure for the calling method. 

server alias (string) 

The implementation alias of the server to be disabled, 
rc (ORBStatus) 

Returns 0 for success or a DSOM error code for failure. 



somdDisableServer - Remarks 



The somdDisableServer method disables the server process associated with the server alias. Once a server process has been disabled, it 
cannot be restarted until it is explicitly enabled again. Initially, all server processes are enabled by default. Note: If the server process to be 
disabled is currently running, then it is first stopped before disabling. If the method is unsuccessful in stopping the server, the disable method 
fails. 



somdDisableServer - Original Class 

SOMDServerMgr 



somdDisableServer - Related Methods 

Methods 

• somdEnableServer 



somdDisableServer - Example Code 




#include <somd.h> 

#include <servmgr.h> 

SOMDServerMgr servmgr; 

string server_alias = "MyServer"; 

ORBStatus rc; 

Environment e; 

SOM_InitEnvironment (&e) ; 

SOMD_Init (&e) ; 

servmgr = SOMDServerMgrNew ( ) ; 

rc = _somdDisableServer (servmgr, &e, server_alias) ; 



somdDisableServer - Topics 



Select an item: 
Syntax 
Parameters 
Returns 
Remarks 
Original Class 
Example Code 
Related Methods 
Glossary 



somdEnableServer 



somdEnableServer - Syntax 



This method enables a server process so that it can be started when required. Initially, all server processes are enabled by default. 



SOMDServerMgr 

Environment 

string 

ORBStatus 



receiver; 

*env; 

server_alias ; 
rc; 



rc = somdEnableServer (receiver, env, server_alias) ; 



somdEnableServer Parameter - receiver 



receiver (SOMDServerMgr) 

A pointer to an object of class SOMDServerMgr. 



somdEnableServer Parameter - env 



env (Environment *) 

A pointer to the Environment structure for the calling method. 



somdEnableServer Parameter - server alias 



serveralias (string) 

The implementation alias of the server to be enabled. 



somdEnableServer Parameter - rc 



rc (ORBStatus) 

Returns 0 for success or a DSOM error code for failure. 



somdEnableServer - Parameters 



receiver (SOMDServerMgr) 

A pointer to an object of class SOMDServerMgr. 

env (Environment *) 

A pointer to the Environment structure for the calling method. 

server alias (string) 

The implementation alias of the server to be enabled, 
rc (ORBStatus) 

Returns 0 for success or a DSOM error code for failure. 



somdEnableServer - Remarks 



The somdEnableServer method enables a server process associated with the server alias. Initially, all server processes are enabled by 
default. Server processes can be disabled by using the somdDisableServer method. 



somdEnableServer - Original Class 




SOMDServerMgr 



somdEnableServer - Related Methods 



Methods 



somdDisableServer 



somdEnableServer - Example Code 



SOMDServerMgr servmgr; 

string server_alias = "MyServer"; 

ORBStatus rc; 

Environment e; 

SOM_InitEnvironment (&e) ; 

SOMD_Init (&e) ; 

servmgr = SOMDServerMgrNew ( ) ; 

/* disable the server */ 

rc = _somdDisableServer ( servmgr , &e, server_alias) ; 
/* do some processing */ 

/* enable the server */ 

rc = _somdEnableServer (servmgr, &e, server_alias) ; 



somdEnableServer - Topics 



Select an item: 
Syntax 
Parameters 
Returns 
Remarks 
Original Class 
Example Code 
Related Methods 
Glossary 



somdlsServerEnabled 



somdlsServerEnabled - Syntax 



This method determines whether a server process is enabled or not. 



SOMDServerMgr receiver; 

Environment *env; 

ImlementationDef impldef; 

boolean rc; 

rc = somdlsServerEnabled (receiver, env, impldef); 



somdlsServerEnabled Parameter - receiver 



receiver (SOMDServerMgr) 

A pointer to an object of class SOMDServerMgr. 



somdlsServerEnabled Parameter - env 



env (Environment *) 

A pointer to the Environment structure for the calling method. 



somdlsServerEnabled Parameter - impldef 



impldef (ImlementationDef) 

A pointer to the ImplementationDef object for the server, obtained using the find_impldef_by_alias method when it is invoked on 
the global SOMD ImpIRepObject. 



somdlsServerEnabled Parameter - rc 



rc (boolean) 

Returns TRUE if the server is enabled; otherwise, FALSE is returned. 



somdlsServerEnabled - Parameters 



receiver (SOMDServerMgr) 

A pointer to an object of class SOMDServerMgr. 

env (Environment *) 

A pointer to the Environment structure for the calling method, 
impldef (ImlementationDef) 

A pointer to the ImplementationDef object for the server, obtained using the find_impldef_by_alias method when it is invoked on 
the global SOMDJmpIRepObject. 

rc (boolean) 

Returns TRUE if the server is enabled; otherwise, FALSE is returned. 



somdlsServerEnabled - Remarks 



The somdlsServerEnabled method returns a boolean corresponding to the current state (enabled/disabled) of the server process. 



somdlsServerEnabled - Original Class 



SOMDServerMgr 



somdlsServerEnabled - Related Methods 



Methods 

• somDisableServer 

• somEnableServer 



somdlsServerEnabled - Example Code 



#include <somd.h> 

#include <servmgr.h> 

SOMDServerMgr servmgr; 

ImplementationDef impldef; 
string server_alias = "MyServer"; 
boolean rc; 

Environment e; 

SOM_InitEnvironment (&e) ; 

SOMD_Init (&e) ; 

impldef = _f ind_impldef_by_alias (SOMD_ImplRepOb ject , 

&e, server_alias) ; 



servmgr = SOMDServerMgrNew ( ) ; 




/* if server is disabled then enable it*/ 

if ( ! _somdIsServerEnabled (servmgr, &e, impldef ) ) 

rc = _somdEnableServer (servmgr, &e, server_alias) 



somdlsServerEnabled - Topics 



Select an item: 
Syntax 
Parameters 
Returns 
Remarks 
Original Class 
Example Code 
Related Methods 
Glossary 



somdListServer 



somdListServer - Syntax 



This method queries the state of a server process. 



SOMDServerMgr 

Environment 

string 

ORBStatus 



receiver; 

*env; 

server_alias ; 
rc; 



rc = somdListServer (receiver , env, server_alias) ; 



somdListServer Parameter - receiver 



receiver (SOMDServerMgr) 

A pointer to an object of class SOMDServerMgr. 



somdListServer Parameter - env 



env (Environment *) 

A pointer to the Environment structure for the calling method. 



somdListServer Parameter - server alias 



serveralias (string) 

The implementation alias of the server to be listed. 



somdListServer Parameter - rc 



rc (ORBStatus) 

Returns 0 if the server process is running; otherwise, a DSOM error code is returned. 



somdListServer - Parameters 



receiver (SOMDServerMgr) 

A pointer to an object of class SOMDServerMgr. 

env (Environment *) 

A pointer to the Environment structure for the calling method. 

server alias (string) 

The implementation alias of the server to be listed, 
rc (ORBStatus) 

Returns 0 if the server process is running; otherwise, a DSOM error code is returned. 



somdListServer - Remarks 



The somdListServer method is invoked to query the status of the server process associated with the server alias. If the server process is 
running, the return code will be 0 indicating success. 



somdListServer - Original Class 

SOMDServerMgr 



somdListServer - Example Code 




#include <somd.h> 

#include <servmgr.h> 

SOMDServerMgr servmgr; 

string server_alias = "MyServer"; 

ORBStatus rc; 

Environment e; 

SOM_InitEnvironment (&e) ; 

SOMD_Init (&e) ; 

servmgr = SOMDServerMgrNew ( ) ; 

rc = _somdListServer ( servmgr , &e, server_alias) ; 
if (!rc) /* server is running */ 

rc = _somdShutdownServer (servmgr, &e, server_alias) ; 
else if (rc == SOMDERROR_ServerNotFound) 

/* server is not running */ 
rc = _somdStartServer (servmgr, &e, server_alias) ; 



somdListServer - Topics 



Select an item: 
Syntax 
Parameters 
Returns 
Remarks 
Original Class 
Example Code 
Glossary 



somdRestartServer 



somdRestartServer - Syntax 



This method restarts a server process. 



SOMDServerMgr 

Environment 

string 

ORBStatus 



receiver; 

*env; 

server_alias ; 
rc; 



rc = somdRestartServer (receiver, env, server_alias) ; 



somdRestartServer Parameter - receiver 



receiver (SOMDServerMgr) 

A pointer to an object of class SOMDServerMgr. 



somdRestartServer Parameter - env 



env (Environment *) 

A pointer to the Environment structure for the calling method. 



somdRestartServer Parameter - server alias 



serveralias (string) 

The implementation alias of the server to be restarted. 



somdRestartServer Parameter - rc 



rc (ORBStatus) 

Returns 0 for success or a DSOM error code for failure. 



somdRestartServer - Parameters 



receiver (SOMDServerMgr) 

A pointer to an object of class SOMDServerMgr. 

env (Environment *) 

A pointer to the Environment structure for the calling method. 

server alias (string) 

The implementation alias of the server to be restarted, 
rc (ORBStatus) 

Returns 0 for success or a DSOM error code for failure. 



somdRestartServer - Remarks 



The somdRestartServer method is invoked to restart a server process. If the server process currently exists, it will be stopped and started 




again. If the server process does not exist, a new server process will still be started. If the server process cannot be stopped and/or started 
for any reason, the method returns a DSOM error code. 

Note: If the designated server is registered in the Implementation Repository (on the server's machine) as "nonstoppable” (via the regimpl 
”-n" option), then the method will return an error. 



somdRestartServer - Original Class 

SOMDServerMgr 



somdRestartServer - Example Code 



#include <somd.h> 

#include <servmgr.h> 

SOMDServerMgr servmgr; 

string server_alias = "MyServer"; 

ORBStatus rc; 

Environment e; 

SOM_InitEnvironment (&e) ; 

SOMD_Init (&e) ; 

servmgr = SOMDServerMgrNew ( ) ; 

rc = _somdRe start Server ( servmgr , &e, server_alias) ; 



somdRestartServer - Topics 



Select an item: 
Syntax 
Parameters 
Returns 
Remarks 
Original Class 
Example Code 
Glossary 



somdShutdownServer 



somdShutdownServer - Syntax 



This method stops a server process. 



SOMDServerMgr receiver; 

Environment *env; 

string server_alias ; 

ORBStatus rc; 

rc = somdShutdownServer (receiver, env, server_alias) ; 



somdShutdownServer Parameter - receiver 



receiver (SOMDServerMgr) 

A pointer to an object of class SOMDServerMgr. 



somdShutdownServer Parameter - env 



env (Environment *) 

A pointer to the Environment structure for the calling method. 



somdShutdownServer Parameter - server alias 



server alias (string) 

The implementation alias of the server to be stopped. 



somdShutdownServer Parameter - rc 



rc (ORBStatus) 

Returns 0 for success or a DSOM error code for failure. 



somdShutdownServer - Parameters 



receiver (SOMDServerMgr) 

A pointer to an object of class SOMDServerMgr. 

env (Environment *) 

A pointer to the Environment structure for the calling method. 



server alias (string) 

The implementation alias of the server to be stopped, 
rc (ORBStatus) 

Returns 0 for success or a DSOM error code for failure. 



somdShutdownServer - Remarks 



The somdShutdownServer method is invoked to stop a server process. If the server process corresponding to the server alias exists, it will 
be stopped and a code indicating success is returned. 

Note: If the designated server is registered in the Implementation Repository (on the server's machine) as "nonstoppable” (via the regimpl 
”-n" option), then this method will return an error. 

Note: On AIX, this method will fail to stop the server process if the process owner executing this method is not the same as that of either the 
server process or root. 



somdShutdownServer - Original Class 



SOMDServerMgr 



somdShutdownServer - Example Code 



#include <somd.h> 

#include <servmgr.h> 

SOMDServerMgr servmgr; 

string server_alias = "MyServer"; 

ORBStatus rc; 

Environment e; 

SOM_InitEnvironment (&e) ; 

SOMD_Init (&e) ; 

servmgr = SOMDServerMgrNew ( ) ; 

rc = _somdShutdownServer ( servmgr, &e, server_alias) ; 



somdShutdownServer - Topics 



Select an item: 
Syntax 
Parameters 
Returns 
Remarks 
Original Class 
Example Code 
Glossary 



somdStartServer 



somdStartServer - Syntax 



This method starts a server process. 



SOMDServerMgr receiver; 

Environment *env; 

string server_alias; 

ORBStatus rc; 

rc = somdStartServer (receiver, env, server_alias) ; 



somdStartServer Parameter - receiver 



receiver (SOMDServerMgr) 

A pointer to an object of class SOMDServerMgr. 



somdStartServer Parameter - env 



env (Environment *) 

A pointer to the Environment structure for the calling method. 



somdStartServer Parameter - server alias 



server alias (string) 

The implementation alias of the server to be started. 



somdStartServer Parameter - rc 



rc (ORBStatus) 

Returns 0 for success or a DSOM error code for failure. 



somdStartServer - Parameters 



receiver (SOMDServerMgr) 

A pointer to an object of class SOMDServerMgr. 

env (Environment *) 

A pointer to the Environment structure for the calling method. 

server alias (string) 

The implementation alias of the server to be started, 
rc (ORBStatus) 

Returns 0 for success or a DSOM error code for failure. 



somdStartServer - Remarks 



The somdStartServer method is invoked to start a server process. If the server process does not exist, the server process is started and 
the code indicating success is returned. If the server process already exists, then the return code will still indicate success and the server 
process will be undisturbed. 



somdStartServer - Original Class 



SOMDServerMgr 



somdStartServer - Example Code 



#include <somd.h> 

#include <servmgr.h> 

SOMDServerMgr servmgr; 

string server_alias = "MyServer"; 

ORBStatus rc; 

Environment e; 

SOM_InitEnvironment (&e) ; 

SOMD_Init (&e) ; 

servmgr = SOMDServerMgrNew ( ) ; 

rc = _somdStartServer ( servmgr, &e, server_alias) ; 




somdStartServer - Topics 



Select an item: 
Syntax 
Parameters 
Returns 
Remarks 
Original Class 
Example Code 
Glossary 



SOMOA 



File stem: somoa 

Base 

BOA 

Metaclass 

SOMMSinglelnstance 

Ancestor Classes 
BOA 

SOMOBject 

Description 

The SOMOA class is DSOM's basic object adapter. SOMOA is a subclass of the abstract BOA class, and provides implementations of all 
the BOA methods. The SOMOA class also introduces methods for receiving and dispatching requests on SOM objects. SOMOA provides 
some additional methods for creating and managing object references. 

New methods 

The following list shows all the SOMOA methods. 

• activate_impl_failed* 

• changejd* 

• create_constant* 

• create_SOM_ref* 

• execute_next_request* 

• execute_request_loop* 

• get_SOM_object* 

(* This class and its methods were added by DSOM to supplement the published CORBA 1 .1 interfaces.) 

Overridden methods 

The following list shows all the methods overridden by the SOMOA class. These methods are overridden in order to modify the behavior 
defined by an ancestor class. 

• changejmplementation 

• create 

• deactivatejmpl 

• deactivate_obj 

• dispose 

• getjd 

• get_principal 

• impl_is_ready 

• obj_is_ready 

• set_exception 



somlnit 

somllninit 



activatejmpl_failed 



activatejmpl_failed - Syntax 



This message sends a message to the DSOM daemon indicating that a server did not activate. 



SOMOA 

Environment 

ImplementationDef 

long 



receiver; 
*env; 
implDef ; 
rc; 



activate_impl_f ailed (receiver, env, 
implDef, rc) ; 



activatejmpl_failed Parameter - receiver 



receiver (SOMOA) 

A pointer to the SOMOA object that attempted to activate the implementation. 



activatejmpl_failed Parameter - env 



env (Environment *) 

A pointer to the Environment structure for the method caller. 



activateJmpLfailed Parameter - implDef 



implDef (ImplementationDef) 

A pointer to the ImplementationDef object representing the implementation that failed to activate. 



activate_impl_failed Parameter - rc 



rc (long) 

A return code designating the reason for failure. 



activateJmpLfailed Parameter - rc 



activatejmpl_failed - Parameters 



receiver (SOMOA) 

A pointer to the SOMOA object that attempted to activate the implementation, 
env (Environment *) 

A pointer to the Environment structure for the method caller. 
impIDef (ImplementationDef) 

A pointer to the ImplementationDef object representing the implementation that failed to activate, 
rc (long) 

A return code designating the reason for failure. 



rc 



activate_impl_failed - Remarks 



The activate_impl_failed method sends a message to the DSOM daemon (somdd) indicating that the server did not activate. 



activatejmpljailed - Original Class 

SOMOA 



activatejmpljailed - Example Code 



#include <somd.h> /* needed by all servers */ 
main(int argc, char **argv) 




{ 

Environment ev; 

SOM_InitEnvironment (&ev) ; 

/* Initialize the DSOM run-time environment */ 

SOMD_Init (&ev) ; 

/* Retrieve its ImplementationDef from the Implementation 
Repository by passing its implementation ID as a key */ 
SOMD_ImplDefOb ject = 

_f ind_impldef (SOMD_ImplRepOb ject , &ev, argv[l]); 

/* create the SOMOA */ 

S OMD_S 0M0 AOb ject = SOMOANewO; 

/* suppose something went wrong with server initialization */ 

/* tell the daemon (via SOMOA) that activation failed */ 

_a c t i vat e_imp l_failed(S OMD_S 0M0 AOb ject, 

&ev, SOMD_ImplDefOb ject , rc) ; 



activatejmpl failed - Topics 



Select an item: 
Syntax 
Parameters 
Returns 
Remarks 
Original Class 
Example Code 
Glossary 



changejd 



changejd - Syntax 



This method changes the reference data associated with an object. 



SOMOA 

Environment 

SOMDObject 

ReferenceData 



receiver; 
*env; 
ob jref ; 
id; 



change_id (receiver, env, objref, id); 



changejd Parameter - receiver 



receiver (SOMOA) 

A pointer to the SOMOA object managing the implementation. 



changejd Parameter - env 



env (Environment *) 

A pointer to the Environment structure for the method caller. 



changejd Parameter - objref 



objref (SOMDObject) 

A pointer to the SOMDObject which identifies the object. 



changejd Parameter - id 



id (ReferenceData) 

A pointer to the ReferenceData structure representing the object to be created. 



changejd Parameter - rc 



changejd - Parameters 



receiver (SOMOA) 

A pointer to the SOMOA object managing the implementation, 
env (Environment *) 

A pointer to the Environment structure for the method caller, 
objref (SOMDObject) 

A pointer to the SOMDObject which identifies the object. 




id (ReferenceData) 

A pointer to the ReferenceData structure representing the object to be created. 



rc 



changejd - Remarks 



The changejd changes the ReferenceData associated with the object identified by ob/ref. The ReferenceData previously stored in the 
SOMOA's reference data table is replaced with the value of /d. The new ID cannot be larger than the maximum size of the original 
ReferenceData (usually specified as 1024 bytes). 



changejd - Example Code 



#include <somd.h> 

#include <repostry.h> 

#include <intfacdf.h> 

SOMDObject objref; 

ReferenceData idl, id2; 

InterfaceDef intfdef; 

objref = _create (SOMD_SOMOAOb ject , &ev, idl, 
intfdef, SOMD_ImplDefOb ject ) ; 

/* change the ReferenceData associated with a SOMDObject */ 
_change_id (SOMD_SOMOAOb ject , &ev, objref, id2); 



changejd - Topics 



Select an item: 

Syntax 

Parameters 

Returns 

Remarks 

Example Code 

Glossary 



create constant 



create_constant - Syntax 



This method creates a "constant" object reference. 



SOMOA 

Environment 
ReferenceData 
Interf aceDef 
ImplementationDef 
SOMDObject 



receiver; 

*env; 

id; 

intf; 

impl; 

rc; 



rc = create_constant (receiver, env, id, 
intf, impl) ; 



create constant Parameter - receiver 



receiver (SOMOA) 

A pointer to the SOMOA object managing the implementation. 



create constant Parameter - env 



env (Environment *) 

A pointer to the Environment structure for the method caller. 



create constant Parameter - id 



id (ReferenceData) 

A pointer to the ReferenceData structure containing application-specific information describing the target object. 



create constant Parameter - intf 



intf (InterfaceDef) 

A pointer to the InterfaceDef object which describes the interface of the target object. 



create_constant Parameter - impl 



impl (ImplementationDef) 

A pointer to the ImplementationDef object which describes the application (server) process which implements the target object. 



create constant Parameter - rc 



rc (SOMDObject) 

Returns a pointer to a SOMDObject. Ownership of the new object reference is transferred to the caller. 



create constant - Parameters 



receiver (SOMOA) 

A pointer to the SOMOA object managing the implementation, 
env (Environment *) 

A pointer to the Environment structure for the method caller, 
id (ReferenceData) 

A pointer to the ReferenceData structure containing application-specific information describing the target object, 
intf (InterfaceDef) 

A pointer to the InterfaceDef object which describes the interface of the target object, 
impl (ImplementationDef) 

A pointer to the ImplementationDef object which describes the application (server) process which implements the target object, 
rc (SOMDObject) 

Returns a pointer to a SOMDObject. Ownership of the new object reference is transferred to the caller. 



create constant - Remarks 



The create_constant method is a variant of the create method. Like create, it creates an object reference for an object with the specified 
interface and associates the supplied ReferenceData with the object reference. The ReferenceData can later be retrieved using the get_id 
method. Unlike create, this method creates a "contant" reference whose ID value cannot be changed. (See the changejd method of 
SOMOA.) This is because the ID is maintained as a constant part of the object reference state, versus stored in the reference data table for 
the server. 

This method would be used whenever the application prefers not to maintain an object's ReferenceData in the server's reference data table. 



create_constant - Original Class 

SOMOA 



create constant - Related Methods 




Methods 



• create 

• create_SOM_ref 

• dispose 

• getjd 

• is_constant 



create_constant - Example Code 



#include <somd.h> 

#include <repostry.h> 

#include <intfacdf.h> 

Environment ev; 

ReferenceData id; 

InterfaceDef intfdef; 

SOMDObject objref; 

string fname; /* file name to be saved with reference */ 

/* create the id for the reference */ 
id._maximum = id._length = strlen (fname) +1 ; 
id._buffer = (string) SOMMalloc (strlen (fname) +1) ; 
strcpy (id._buffer, fname) ; 

/* get the interface def object for interface Foo*/ 
intfdef = _lookup_id (SOM_Interf aceRepository, &ev, "Foo"); 

objref = _create_constant (SOMD_SOMOAOb ject , 

&ev, id, intfdef, SOMD_ImplDefOb ject ) ; 



create_constant - Topics 



Select an item: 
Syntax 
Parameters 
Returns 
Remarks 
Original Class 
Example Code 
Related Methods 
Glossary 



create SOM ref 



create_SOM_ref - Syntax 



This method creates a simple, transient DSOM reference to a SOM object. 



SOMOA 

Environment 

SOMObject 

ImplementationDef 

SOMDObject 



receiver; 
*env; 
somobj ; 
impl; 
rc; 



rc = create_SOM_ref (receiver , env, somobj, 
impl) ; 



create SOM ref Parameter - receiver 



receiver (SOMOA) 

A pointer to the SOMOA object managing the implementation. 



create SOM ref Parameter - env 



env (Environment *) 

A pointer to the Environment structure for the method caller. 



create_SOM_ref Parameter - somobj 



somobj (SOMObject) 

A pointer to the local SOMObject to be referenced. 



create_SOM_ref Parameter - impl 



impl (ImplementationDef) 

A pointer to the ImplementationDef of the calling server process. 



create SOM ref Parameter - rc 



rc (SOMDObject) 

Returns a pointer to a SOMDObject. Ownership of the new object reference is transferred to the caller. 



create SOM ref - Parameters 



receiver (SOMOA) 

A pointer to the SOMOA object managing the implementation, 
env (Environment *) 

A pointer to the Environment structure for the method caller, 
somobj (SOMObject) 

A pointer to the local SOMObject to be referenced, 
impl (ImplementationDef) 

A pointer to the ImplementationDef of the calling server process, 
rc (SOMDObject) 

Returns a pointer to a SOMDObject. Ownership of the new object reference is transferred to the caller. 



create SOM ref - Remarks 



The create_SOM_ref method creates a simple DSOM reference (SOMDObject) for a local SOM object. The reference is "special" in that 
there is no explicit ReferenceData associated with the object. Also, this object reference is only valid while the target SOM object exists. 

The SOMObject associated with the SOM_ref can be retrieved via the get_SOM_object method. The is_SOM_ref method of SOMDObject 
can be used to tell if the reference was created using create_SOM_ref or not. 



create_SOM_ref - Original Class 



SOMOA 



create SOM ref - Related Methods 



Methods 

• get_SOM_object 

• is_SOM_ref 



create_SOM_ref - Example Code 




#include <somd.h> 



SOMDObject objref; 

Environment ev; 

SOMObject obj; 

/* one might want to make this call as part of the code 

* that overrides the somdRefFromSOMOb j method, i.e. 

* in an implementation of a subclass of SOMDServer. 

*/ 

objref = _create_SOM_ref (SOMD_SOMOAOb ject , &ev, 

obj, SOMD_ImplDefOb ject ) 



create_SOM_ref - Topics 



Select an item: 
Syntax 
Parameters 
Returns 
Remarks 
Original Class 
Example Code 
Related Methods 
Glossary 



execute_next_request 



execute_next_request - Syntax 



This method receives a request message, executes the request, and returns to the caller. 



SOMOA 

Environment 

Flags 

ORBStatus 



receiver; 

*env; 

waitFlag; 

rc; 



rc = execute_next_request (receiver, 
env, waitFlag) ; 



execute_next_request Parameter - receiver 



receiver (SOMOA) 

A pointer to the SOMOA object managing the implementation. 



execute_next_request Parameter - env 



env (Environment *) 

A pointer to the Environment structure for the method caller. 



execute_next_request Parameter - waitFlag 



waitFlag (Flags) 

A Flags value (unsiqned Iona) indicating whether the method should block if there is no message pending (SOMD WAIT) or return 
with an error (SOMD_NO_WAIT). 



execute_next_request Parameter - rc 



rc (ORBStatus) 

Returns an ORBStatus value representing the return value for the operation. SOMDERROR_NoMessages is returned if the method 
is invoked with SOMD_NO_WAIT and no message is available. 



execute_next_request - Parameters 



receiver (SOMOA) 

A pointer to the SOMOA object managing the implementation, 
env (Environment *) 

A pointer to the Environment structure for the method caller. 
waitFlag (Flags) 

A Flags value (unsiqned lonq) indicating whether the method should block if there is no message pendinq (SOMD WAIT) or return 
with an error (SOMD_NO_WAIT). 



rc (ORBStatus) 

Returns an ORBStatus value representing the return value for the operation. SOMDERROR_NoMessages is returned if the method 
is invoked with SOMD_NO_WAIT and no message is available. 



execute_next_request - Remarks 




The execute_next_request method receives the next request message, executes the request, and sends the result to the caller. 

If the server's ImplementationDef indicates the server is multithreaded (the impl_flags has the IMPLDEF_MULTI_THREAD flag set), each 
request will be run by SOMOA in a separate thread. 



execute_next_request - Original Class 

SOMOA 



execute_next_request - Related Methods 



Methods 



execute_request_loop 



execute_next_request - Example Code 



#include <somd.h> 

/* server initialization code ... */ 

SOM_InitEnvironment (&ev) ; 

/* signal DSOM that server is ready */ 

_impl_is_ready (SOMD_SOMOAOb ject , &ev, SOMD_ImplDefOb ject ) ; 

while (ev._major == NO_EXCEPTION) { 

(void) _execute_next_request (SOMD_SOMOAOb ject , &ev, SOMD_WAIT ) ; 
/* perform appl-specif ic code between messages here, e.g.,*/ 
numMessagesProcessed++ ; 

} 



execute_next_request - Topics 



Select an item: 
Syntax 
Parameters 
Returns 
Remarks 
Original Class 
Example Code 
Related Methods 
Glossary 



execute_request_loop 



execute_request_loop - Syntax 



This method receives a request message, executes the request, and returns the result to the calling client. 



SOMOA receiver; 

Environment *env; 

Flags waitFlag; 

ORBStatus rc; 

rc = execute_request_loop (receiver , 
env, waitFlag) ; 



execute_request_loop Parameter - receiver 



receiver (SOMOA) 

A pointer to the SOMOA object managing the implementation. 



execute_request_loop Parameter - env 



env (Environment *) 

A pointer to the Environment structure for the method caller. 



execute_request_loop Parameter - waitFlag 



waitFlag (Flags) 

A Flags bitmask (unsigned long) indicating whether the method should block (SOMD_WAIT) or return to the caller 
(SOMD_NO_WAIT) when there is no request message pending. 



execute_request_loop Parameter - rc 



rc (ORBStatus) 

May return an OBJ_ADAPTER exception which contains an DSOM error code for the operation. SOMDERROR_NoMessages is 
returned as an ORBStatus code if the method is invoked with SOMD_NO_WAIT and no message is pending. 



execute_request_loop - Parameters 



receiver (SOMOA) 

A pointer to the SOMOA object managing the implementation, 
env (Environment *) 

A pointer to the Environment structure for the method caller. 
waitFlag (Flags) 

A Flags bitmask (unsigned long) indicating whether the method should block (SOMD_WAIT) or return to the caller 
(SOMD_NO_WAIT) when there is no request message pending. 



rc (ORBStatus) 

May return an OBJ_ADAPTER exception which contains an DSOM error code for the operation. SOMDERROR_NoMessages is 
returned as an ORBStatus code if the method is invoked with SOMD_NO_WAIT and no message is pending. 



execute_request_loop - Remarks 



The execute_request_loop method initiates a loop that waits for a request message, executes the request, and returns the result to the 
client who invoked the request. When called with the SOMD_WAIT flag, this method loops infinitely (or until an error). When called with the 
SOMD_NO_WAIT flag, this method loops as long as it finds a request message to process. 

The SOMD_NO_WAIT flag is useful when writing event-driven applications where there are event sources other than DSOM requests (e.g., 
user input, etc.). In this case, DSOM cannot be given exclusive control. Instead, a DSOM event handler can be written using the 
SOMD_NO_WAIT option, to process all pending requests before returning control to the event manager. 

If the server's ImplementationDef indicates the server is multithreaded (the impl_flags has the IMPLDEF_MULTI_TFIREAD flag set), each 
request will be run by SOMOA in a separate thread (OS/2 only). 

See Chapter 9 of the SOM Too/k/t User's Guide for a description of the Event Manager (EMan) framework, for writing event-driven 
applications. 



execute_request_loop - Original Class 

SOMOA 



execute_request_loop - Related Methods 



Functions 



SOMDRegisterCallback 



Methods 



execute_next_req uest 




execute_request_loop - Example Code 



#include <somd.h> 

/* server initialization code ... */ 

_impl_is_ready (SOMD_SOMOAOb ject , &ev, SOMD_ImplDefOb ject ) ; 

/* turn control over to SOMOA */ 

(void) _execute_request_loop (SOMD_SOMOAOb ject , &ev, SOMD_WAIT) ; 



execute_request_loop - Topics 



Select an item: 
Syntax 
Parameters 
Returns 
Remarks 
Original Class 
Example Code 
Related Methods 
Glossary 



get_SOM_object 



get_SOM_object - Syntax 



Get the SOM object associated with a simple DSOM reference. 



SOMOA 

Environment 

SOMDObject 

SOMObject 



receiver; 

*env; 
somref ; 

rc; /* Returns the SOM object associated with the reference. 



rc = _get_SOM_ob ject (receiver, env, 
somref) ; 



get_SOM_object Parameter - receiver 



receiver (SOMOA) 

A pointer to the SOMOA object managing the implementation. 



get_SOM_object Parameter - env 



env (Environment *) 

A pointer to the Environment structure for the method caller. 



get_SOM_object Parameter - somref 



somref (SOMDObject) 

A pointer to a SOMDObject created by the create_SOM_ref method. 



get_SOM_object Parameter - rc 



rc (SOMObject) 

Returns the SOM object associated with the reference. 



get_SOM_object - Parameters 



receiver (SOMOA) 

A pointer to the SOMOA object managing the implementation, 
env (Environment *) 

A pointer to the Environment structure for the method caller, 
somref (SOMDObject) 

A pointer to a SOMDObject created by the create_SOM_ref method, 
rc (SOMObject) 

Returns the SOM object associated with the reference. 



get_SOM_object - Remarks 



The get_SOM_object method returns the SOM object associated with a reference created by the create_SOM_ref method. 




get_SOM_object - Original Class 

SOMOA 



get_SOM_object - Related Methods 



Methods 



create_SOM_ref 

is_SOM_ref 



get_SOM_object - Example Code 



#include <somd.h> 

SOMDObject objref; 

Environment ev; 

SOMObject obj; 

if (_is_SOM_ref (objref, Sev) ) 

/* we know objref is a simple reference, so we can ... */ 
obj = _get_SOM_ob ject (SOMD_SOMOAObject, Sev, objref); 



get_SOM_object - Topics 



Select an item: 
Syntax 
Parameters 
Returns 
Remarks 
Original Class 
Example Code 
Related Methods 
Glossary 



Interface Repository Framework Reference 



AttributeDef 



File stem: attribdf 
Base 
Contained 
Metaclass 

SOMCIass 



Ancestor Classes 
Contained 

SOMOBject 

Description 



Types 



AttributeMode 



{NORMAL, READONLY} 



struct AttributeDescription 

Identifier name; 

Repositoryld id; 

Repositoryld defined_in; 

TypeCode type; 

AttributeMode mode; 



The describe method, inherited from Contained, returns an AttributeDescription structure in the "value" member of the Description 
structure (defined in the Contained class). 

Attributes 

Listed below is each available attribute, with its corresponding type in parentheses, followed by a description of its purpose: 
type (TypeCode) 

The TypeCode that represents the type of the attribute. The TypeCode returned by the "_get_" form of the type attribute is 
contained in the receiving AttributeDef object, which retains ownership. Hence, the returned TypeCode should not be freed. To 
obtain a separate copy, use the TypeCode_copy operation. The "_set_" form of the attribute makes a private copy of the 
TypeCode you supply, to keep in the receiving object. You retain ownership of the passed TypeCode. 

mode (AttributeMode) 

The AttributeMode of the attribute (NORMAL or READONLY). 

New methods 

There are currently no new methods defined for the AttributeDef class. 

Overridden methods 

The following list shows all the methods overridden by the AttributeDef class. These methods are overridden in order to modify the behavior 
defined by an ancestor class. 

• somlnit 

• somUninit 

• somDumpSelf 

• somDumpSelflnit 

• describe 



ConstantDef 




File stem: constdef 



Base 

Contained 

Metaclass 

SOMCIass 



Ancestor Classes 
Contained 

SOMObject 

Description 



Types 



struct ConstantDescription 



Identifier 
Repositoryld 
Repositoryld 
TypeCode 
any value; 

} ; 



name ; 
id; 

def ined_in ; 
type; 



{ 



The describe method, inherited from Contained, returns a ConstantDescription structure in the "value" member of the Description 
structure (defined in the Contained class). 

Attributes 

Listed below is each available attribute, with its corresponding type in parentheses, followed by a description of its purpose: 
type (TypeCode) 

The TypeCode that represents the type of constant. The TypeCode returned by the "_get_" form of the type attribute is contained 
in the receiving ConstantDef object, which retains ownership. Hence, the returned TypeCode should not be freed. To obtain a 
separate copy, use the TypeCode_copy operation. The "_set_" form of the attribute makes a private copy of the TypeCode you 
supply, to keep in the receiving object. You retain ownership of the passed TypeCode. 

value (any) 

The value of the constant. 

New methods 

There are currently no new methods defined for the ConstantDef class. 

Overridden methods 

The following list shows all the methods overridden by the ConstantDef class. These methods are overridden in order to modify the behavior 
defined by an ancestor class. 

• somlnit 

• somUninit 

• somDumpSelf 

• somDumpSelflnt 

• describe 



Contained 



File stem: containd 
Base 



SOMObject 




Metaclass 



SOMCIass 

Ancestor Classes 
SOMObject 

Description 

Types 



typedef string Repositoryld; 

struct Description { 

Identifier name; 
any value; 

}; 



Attributes 

All attributes of the Contained class provide access to information kept within the receiving object. The "_get_" form of the attribute returns 
a memory reference that is only valid as long as the receiving object has not been freed (using _somFree). The "_set_” form of the attribute 
makes a (deep) copy of your data and places it in the receiving object. You retain ownership of all memory references passed using the 
"_set_" attributes. 

Listed below is each available attribute, with its corresponding type in parentheses, followed by a description of its purpose: 
name (Identifier) 

A simple name that identifies the Contained object within its containment hierarchy. The name may not be unique outside of the 
containment hierarchy: thus it may require qualification by ModuleDef name and/or InterfaceDef name. 

id (Repositoryld) 

The value of the "id" field of the Contained object. This is a string that uniquely identifies any object in the IR; thus it needs no 
qualification. Note that Repositorylds have no relationship to the SOM type somld. 

definedjn (Repositoryld) 

The value of the "definedjn" field of the Contained object. This ID uniquely identifies the container where the Contained object is 
defined. Objects without global scope that do not appear within any other object are, by default, placed in the Repository object. 

somModifiers (sequence <somModifier>) 

The somModifiers attribute is a sequence containing all modifiers associated with the object in the "implementation” section of the 
SOM IDL file where the receiving object is defined. 

Note: This attribute is a SOM-unique extension of the Interface Repository; it is not stipulated by the CORBA specification. 

New methods 

The following list shows all the Contained methods. 

• within 

• describe 

Overridden methods 

The following list shows all the methods overridden by the Contained class. These methods are overridden in order to modify the behavior 
defined by an ancestor class. 

• somFree 

• somlnit 

• somUninit 

• somDumpSelf 

• somDumpSelflnt 



describe 




describe - Syntax 



This method returns a structure containing information defined in the IDL specification that corresponds to a specified Contained object 
the Interface Repository. 



Contained 

Environment 

Description 



receiver; 

*env; 

rc; 



rc = describe (receiver, env) ; 



describe Parameter - receiver 



receiver (Contained) 

A pointer to the Contained object in the Interface Repository for which a Description is needed. 



describe Parameter - env 



env (Environment *) 

A pointer to the Environment structure for the caller. 



describe Parameter - rc 



rc (Description) 

Returns a structure of type Description containing information defined in the IDL specification of the receiving object. 



describe - Parameters 



receiver (Contained) 

A pointer to the Contained object in the Interface Repository for which a Description is needed, 
env (Environment *) 

A pointer to the Environment structure for the caller, 
rc (Description) 

Returns a structure of type Description containing information defined in the IDL specification of the receiving object. 



describe - Remarks 



The describe method returns a structure containing information defined in the IDL specification of a Contained object. The specified object 
represents a component of an IDL interface (class) definition maintained within the Interface Repository. 

When finished using the information in the returned Description structure, the client code must release the storage allocated for it. To free 
the associated storage, use a call similar to this: 

if (desc .value ._value) 

SOMFree (desc .value ._value) ; 



CAUTION: 

The describe method returns pointers to elements within objects (for example, name). Thus, the somFree method should not be used to 
release any of these objects while the describe information is still needed. 



The "name" field of the Description is the name of the type of description. The "name" values are from the following set: 
{"ModuleDescription", "InterfaceDescription", "AttributeDescription”, 

"OperationDescription", "ParameterDescription", "TypeDescription", 

"ConstantDescription", "ExceptionDescription"} 

The "value" field is a structure of type any whose ”_value" field is a pointer to a structure of the type named by the "name" field of the 
Description. This structure provides all of the information contained in the IDL specification of the receiver. For example, if the describe 
method is invoked on an object of type AttributeDef, the "name" field of the returned Description will contain the identifier 
"AttributeDescription” and the "value" field will contain an any structure whose ”_value" field is a pointer to an AttributeDescription 
structure. 



describe - Original Class 



Contained 



describe - Related Methods 



Methods 



within 



describe - Example Code 



#include <containd.h> 
#include <attribdf.h> 
#include <somtc.h> 



AttributeDef attr; /* An AttributeDef object (also a Contained) */ 
Description desc; /* .value field will be an AttributeDescription */ 




AttributeDescription *ad; 
Environment *ev; 



desc = Contained_describe (attr, ev) ; 
ad = (AttributeDescription *) desc . value ._value; 
printf ("Attribute name: %s, defined in: %s\n" , 
ad->name, ad->def ined_in) ; 
printf ("Attribute type: "); 

TypeCode_print (ad->type, ev) ; 

printf ("Attribute mode: %s\n", ad->mode == AttributeDef_READONLY ? 
"READONLY" : "NORMAL"); 

SOMFree (desc . value ._value) ; /* Finished with describe output */ 
SOMOb ject_somFree (attr) ; /* Finished with AttributeDef object */ 



describe - Topics 



Select an item: 
Syntax 
Parameters 
Returns 
Remarks 
Original Class 
Example Code 
Related Methods 
Glossary 



within 



within - Syntax 



This method returns a list of objects (in the Interface Repository) that contain a specified Contained object. 



Contained 
Environment 
sequence <container> 



receiver; 

*env; 

rc; 



rc = within (receiver , env) ; 



within Parameter - receiver 



receiver (Contained) 

A pointer to a Contained object for which containing objects are needed. 



within Parameter - env 



env (Environment *) 

A pointer to the Environment structure for the caller. 



within Parameter - rc 



rc (sequence <container>) 

Returns a sequence of Container objects that contain the specified Contained object. 



within - Parameters 



receiver (Contained) 

A pointer to a Contained object for which containing objects are needed, 
env (Environment *) 

A pointer to the Environment structure for the caller, 
rc (sequence <container>) 

Returns a sequence of Container objects that contain the specified Contained object. 



within - Remarks 



The within method returns a sequence of objects within the Interface Repository that contain the specified Contained object. If the 
receiving object is an InterfaceDef or ModuleDef, it can only be contained by the object that defines it. Other objects can be contained by 
objects that define or inherit them. 

If the object is global in scope, the sequence returned by within will have its Jength field set to zero. 

When finished using the sequence returned by this method, the client code is responsible for releasing each of the Containers in the 
sequence and freeing the sequence buffer. In C, this can be accomplished as follows: 

if (seq. Jength) { 
long i; 
for (i=0; i 

_somFree (seq._buf fer [i] ) ; /* Release each Container obj */ 

SOMFree (seq._buf fer) ; /* Release the sequence buffer */ 

} 



within - Original Class 




Contained 



within - Related Methods 



Methods 



describe 



within - Example Code 



#include <containd.h> 
#include <containr.h> 



Contained anObj; 

Environment *ev; 
sequence (Container) sc; 
long i; 

sc = Contained_within (anObj, ev) ; 

printf ("%s is contained in (or inherited by) :\n" , 

Contained get_name (anObj, ev) ) ; 

for (i=0; i 

printf ("\t%s\n". 

Contained get_name ((Contained) sc ._buf fer [ i ] , ev) ) ; 

SOMOb ject_somFree (sc ._buf fer [i] ) ; 

} 

if (sc._length) 

SOMFree (sc ._buf fer) ; 



within - Topics 



Select an item: 
Syntax 
Parameters 
Returns 
Remarks 
Original Class 
Example Code 
Related Methods 
Glossary 



Container 



File stem: containr 



Base 



SOMObject 

Metaclass 

SOMCIass 

Ancestor Classes 
SOMObject 

Description 

Types 

typedef string Inter f aceName; 

// Valid values for Interf aceName are limited to the following set: 
// { "AttributeDef " , "ConstantDef " , "ExceptionDef " , " Inter faceDef " , 

// "ModuleDef", "ParameterDef " , "OperationDef " , "TypeDef", "all"} 

struct ContainerDescription { 

Contained * contained_ob ject ; 

Identifier name; 
any value; 

} ; 



New methods 

The following list shows all the Container methods. 

• contents 

• lookup_name 

• describe_contents 

Overridden methods 

The following list shows all the methods overridden by the Container class. These methods are overridden in order to modify the behavior 
defined by an ancestor class. 

• somlnit 

• somUninit 

• somDumpSelf 

• somDumpSelflnt 



contents 



contents - Syntax 



This method returns a sequence indicating the objects contained within a specified Container object of the Interface Repository. 



Container 
Environment 
Interf aceName 
boolean 

sequence<Contained> 



receiver; 

*env; 

limit_type; 

exclude_inherited; 

rc; 



rc = contents (receiver, env, limit_type. 



exclude_inherited) ; 



contents Parameter - receiver 



receiver (Container) 

A pointer to a Container object whose contained objects are needed. 



contents Parameter - env 



env (Environment *) 

A pointer to the Environment structure for the caller. 



contents Parameter - limit_type 



limit_type (InterfaceName) 

The name of one interface type (see the valid list above) or "all", to specify what type of objects the contents method should search 
for. 



contents Parameter - exclude inherited 



excludejnherited (boolean) 

A boolean value: TRUE to exclude any inherited objects, or FALSE to include all objects. 



contents Parameter - rc 



rc (sequence<Contained>) 

Returns a sequence of pointers to objects contained within the specified Container object. 



contents - Parameters 




receiver (Container) 

A pointer to a Container object whose contained objects are needed, 
env (Environment *) 

A pointer to the Environment structure for the caller. 

Iimit_type (InterfaceName) 

The name of one interface type (see the valid list above) or "all", to specify what type of objects the contents method should search 
for. 

excludejnherited (boolean) 

A boolean value: TRUE to exclude any inherited objects, or FALSE to include all objects, 
rc (sequence<Contained>) 

Returns a sequence of pointers to objects contained within the specified Container object. 



contents - Remarks 



The contents method returns a list of objects contained by the specified Container object. Each object represents a component of an IDL 
interface (class) definition maintained within the Interface Repository. 

The contents method is used to navigate through the hierarchy of objects within the Interface Repository. Starting with the Repository 
object, this method can list all of the objects in the Repository, then all of the objects within the ModuleDef objects, then all within the 
InterfaceDef objects, and so on. 

If the "/imit_type" is set to "all”, objects of all interface types are returned: otherwise, only objects of the requested interface type are 
returned. Valid values for InterfaceName are limited to the following set: 

{"AttributeDef", "ConstantDef", "ExceptionDef", "InterfaceDef", 

"ModuleDef", "ParameterDef", "OperationDef", "TypeDef", "all"} 

If "exc/ude_/nher/ted" is set to TRUE, any inherited objects will not be returned. 

When finished using the sequence returned by this method, the client code is responsible for releasing each of the objects in the sequence 
and freeing the sequence buffer. In C, this can be accomplished as follows: 

if (seq._length) { 
long i; 

for (i=0; i <seq ._length; i++ ) 

SOMOb ject_somFree (seq._buf fer [i] ) ; /* Release each object */ 

SOMFree (seq._buf fer) ; /* Release the buffer */ 

} 



contents - Original Class 



Container 



contents - Related Methods 



Methods 

• lookupname 

• describecontents 




contents - Example Code 



#include <containr.h> 



Container anObj; 
Environment *ev; 
sequence (Contained) sc; 
long i; 



sc = Container_contents (anObj, ev, "all", TRUE); 

printf ("%s contains the following objects :\n", 

SOMOb ject_somIsA (anObj, _Contained) ? 

Contained get_name ((Contained) anObj, ev) : 

"The Interface Repository"); 
for ( 1=0 ; i <seq._length; i++) { 

printf ("\t%s\n", 

Contained get_name (sc ._buf fer [i] , ev)); 

SOMOb ject_somFree (sc ._buf fer [i] ) ; 

} 

if (sc._length) 

SOMFree (sc ._buf fer ) ; 

else 

printf ( " \t [none] \n" ) ; 



contents - Topics 



Select an item: 
Syntax 
Parameters 
Returns 
Remarks 
Original Class 
Example Code 
Related Methods 
Glossary 



describe contents 



describe_contents - Syntax 



This method returns a sequence of descriptions of the objects contained within a specified Container object of the Interface Repository. 



Container 
Environment 
Interf aceName 
boolean 
long 

sequence <ContainerDescription> 



receiver; 

*env; 

limit_type; 
exclude_inherited; 
max_returned_ob j s ; 
rc; 



rc = describe_contents (receiver, env, limit_type, 
exclude_inherited, max_returned_ob js) ; 



describe contents Parameter - receiver 



receiver (Container) 

A pointer to a Container object whose contained object descriptions are needed. 



describe contents Parameter - env 



env (Environment *) 

A pointer to the Environment structure for the caller. 



describe_contents Parameter - limit_type 



limit_type (InterfaceName) 

The name of one interface type (see the valid list above) or "all", to specify what type of objects the describe_contents method 
should return. 



describe contents Parameter - exclude inherited 



excludejnherited (boolean) 

A boolean value: TRUE to exclude any inherited objects, or FALSE to include all objects. 



describe_contents Parameter - max_returned_objs 



max_returned_objs (long) 

A long integer indicating the maximum number of objects to be returned by the method, or -1 to indicate no limit is set. 



describe contents Parameter - rc 



rc (sequence <ContainerDescription>) 

Returns a sequence of ContainerDescription structures, one for each object contained within the specified Container object. Each 
ContainerDescription structure has a "contained_object" field, which points to the contained object, as well as "name" and "value" 
fields, which are the result of the describe method. 



describe contents - Parameters 



receiver (Container) 

A pointer to a Container object whose contained object descriptions are needed, 
env (Environment *) 

A pointer to the Environment structure for the caller. 

Iimit_type (InterfaceName) 

The name of one interface type (see the valid list above) or "all", to specify what type of objects the describe_contents method 
should return. 

excludejnherited (boolean) 

A boolean value: TRUE to exclude any inherited objects, or FALSE to include all objects. 

max_returned_objs (long) 

A long integer indicating the maximum number of objects to be returned by the method, or -1 to indicate no limit is set. 
rc (sequence <ContainerDescription>) 

Returns a sequence of ContainerDescription structures, one for each object contained within the specified Container object. Each 
ContainerDescription structure has a "contained_object" field, which points to the contained object, as well as "name" and "value" 
fields, which are the result of the describe method. 



describe contents - Remarks 



The describe_contents method combines the operations of the contents method and the describe method. That is, for each object 
returned by the contents operation, the description of the object is returned by invoking its describe operation. Each object represents a 
component of an IDL interface (class) definition maintained within the Interface Repository. 

If the "/imit_type" is set to "all”, objects of all interface types are returned: otherwise, only objects of the requested interface type are 
returned. Valid values for InterfaceName are limited to the following set: 

("AttributeDef", "ConstantDef", "ExceptionDef", "InterfaceDef", 

"ModuleDef", "ParameterDef", "OperationDef", "TypeDef", "all"} 

If "exc/ude_/nher/ted" is set to TRUE, any inherited objects will not be returned. 

The "max_retumed_objs" argument is used to limit the number of objects that can be returned. If "max_retumed_objs" is set to -1 , the 
results for all contained objects will be returned. 

When finished using the sequence returned by this method, the client code is responsible for freeing the "value._value" field in each 
description, releasing each of the objects in the sequence, and freeing the sequence buffer. In C, this can be accomplished as follows: 




if (seq._length) { 
long i; 

for (i=0; i <seq._length; i++) { 

if (seq._buffer [i] .value ._value) 

/* Release each description */ 
SOMFree (seq._buf fer [i] . value ._value) ; 

SOMOb ject_somFree (seq._buf fer [i] . contained_ob ject ) ; 

/* Release each object */ 

} 

SOMFree (seq._buf fer) ; /* Release the buffer */ 

> 



describe_contents - Original Class 



Container 



describe contents - Related Methods 



Methods 



contents 

describe 

lookupname 



describe_contents - Example Code 



#include <containr.h> 



Container anObj; 

Environment *ev; 

sequence (ContainerDescription) sc; 
long i; 



sc = Container_describe_contents (anObj, ev, "all", FALSE, -1L) ; 
printf ("%s defines or inherits the following objects :\n", 

SOMOb ject_somIsA (anObj, _Contained) ? 

Contained get_name ( (Contained) anObj, ev) : 

"The Interface Repository"); 
for (i=0; i 

printf ("\t%s\n", sc ,_buf fer [ i ] . name) ; 
if (sc ,_buf fer [i] .value ._value) 

SOMFree (sc._buf fer [i] . value ._value) ; 

SOMOb ject_somFree (sc._buf fer [i] . contained_ob ject ) ; 

} 

if (sc._length) 

SOMFree (sc ._buf fer) ; 

else 



printf ( "\t [none] \n" ) ; 




describe_contents - Topics 



Select an item: 
Syntax 
Parameters 
Returns 
Remarks 
Original Class 
Example Code 
Related Methods 
Glossary 



lookup_name 



lookup_name - Syntax 



This method locates an object by name within a specified Container object of the Interface Repository, or within objects contained in the 
Container object. 



Container 

Environment 

Identifier 

long 

Inter faceName 
boolean 

sequence<Contained> 



receiver; 

*env; 

search_name ; 
levels_to_search; 
limit_type ; 
exclude_inherited; 
rc; 



rc = lookup_name (receiver, env, search_name, 
levels_to_search, limit_type, 
exclude_inherited) ; 



lookup_name Parameter - receiver 



receiver (Container) 

A pointer to a Container object in which to locate the object. 



lookup_name Parameter - env 



env (Environment *) 

A pointer to the Environment structure for the caller. 



lookup_name Parameter - search_name 



search_name (Identifier) 

The name of the object to be located. 



lookup_name Parameter - levels_to_search 



levels_to_search (long) 

A long having the value 1 or -1 . 



lookup_name Parameter - limit_type 



limit_type (InterfaceName) 

The name of one interface type (see the valid list above) or "all", to specify what type of object to search for. 



lookup_name Parameter - excludejnherited 

excludejnherited (boolean) 

A boolean value: TRUE to exclude an object when it is inherited, or FALSE to return the object from wherever it is found. 



lookup_name Parameter - rc 



rc (sequence<Contained>) 

Returns a sequence of pointers to objects of the given name contained within the specified Container object, or within objects 
contained in the Container object. 



lookup_name - Parameters 




receiver (Container) 

A pointer to a Container object in which to locate the object, 
env (Environment *) 

A pointer to the Environment structure for the caller. 

search_name (Identifier) 

The name of the object to be located. 

levels_to_search (long) 

A long having the value 1 or -1 . 

Iimit_type (InterfaceName) 

The name of one interface type (see the valid list above) or "all", to specify what type of object to search for. 

exclude_inherited (boolean) 

A boolean value: TRUE to exclude an object when it is inherited, or FALSE to return the object from wherever it is found, 
rc (sequence<Contained>) 

Returns a sequence of pointers to objects of the given name contained within the specified Container object, or within objects 
contained in the Container object. 



lookupjiame - Remarks 



The lookup_name method locates an object by name within a specified Container object, or within objects contained in the Container 
object. The ''search_name " specifies the name of the object to be found. Each object represents a component of an IDL interface (class) 
definition maintained within the Interface Repository. 

The "/ei/e/s_to_search" argument controls whether the lookup is constrained to the specified Container object or whether objects contained 
within the Container object are also searched. The "/eve/s_to_seaA value should be -1 to search the Container and all contained 
objects; it should be 1 to search only the Container itself. 

If "/imit_type " is set to "all", the lookup locates an object of the specified name with any interface type; otherwise, the search locates the 
object only if it has the designated interface type. Valid values for InterfaceName are limited to the following set: 

{"AttributeDef", "ConstantDef", "ExceptionDef", 

"InterfaceDef", "ModuleDef", "ParameterDef", 

"OperationDef", "TypeDef", "all"} 

If "exc/ude_/nherited" is set to TRUE, any inherited objects will not be returned. 

When finished using the sequence returned by this method, the client code is responsible for releasing each of the objects in the sequence 
and freeing the sequence buffer. In C, this can be accomplished as follows: 

if (seq._length) { 
long i; 

for (i=0; i <seq ._length; i++) { 

SOMOb ject_somFree (seq._buf fer [i] ) ; 

/* Release each object */ 

SOMFree (seq._buf fer) ; /* Release the buffer */ 

} 



lookupjiame - Original Class 



Container 



lookupjiame - Related Methods 




Methods 



contents 

describecontents 



lookup_name - Example Code 



#include <containr.h> 
#include <containd.h> 
#include <repostry.h> 



Container repo; 
Environment *ev; 
sequence (Contained) sc; 
long i; 

Identifier nameToFind; 



repo = (Container) RepositoryNew (); 

sc = Container_lookup_name (repo, ev, nameToFind, -1, "all", TRUE) 
printf ("%d object%s found: \n", 

sc._length, sc._length == 1 ? "" : "s"); 
for (i=0; i <seq._length; i++) { 

printf ("\t%s\n", 

Contained get_id (sc._buf fer [i] , ev) ) ; 

SOMOb ject_somFree (sc._buf fer [i] ) ; 

} 

if (sc._length) 

SOMFree (sc ._buf fer) ; 



lookup_name - Topics 



Select an item: 
Syntax 
Parameters 
Returns 
Remarks 
Original Class 
Example Code 
Related Methods 
Glossary 



Exception Def 



File stem: excptdef 



Base 



Contained 



Metaclass 

SOMCIass 

Ancestor Classes 
Contained 

SOMObject 

Description 

Types 



struct ExceptionDescription { 

Identifier name; 

Repositoryld id; 

Repositoryld defined_in; 

TypeCode type; 



The describe method, inherited from Contained, returns an ExceptionDescription structure in the "value" member of the Description 
structure (defined in the Contained class). 

Attributes 

Listed below is each available attribute, with its corresponding type in parentheses, followed by a description of its purpose: 
type (TypeCode) 

The TypeCode that represents the type of the exception. The TypeCode returned by the "_get_" form of the type attribute is 
contained in the receiving ExceptionDef object, which retains ownership. Hence, the returned TypeCode should not be freed. To 
obtain a separate copy, use the TypeCode_copy operation. The "_set_” form of the attribute makes a private copy of the 
TypeCode you supply, to keep in the receiving object. You retain ownership of the passed TypeCode. 

New methods 

There are currently no new methods defined for the ExceptionDef class. 

Overridden methods 

The following list shows all the methods overridden by the ExceptionDef class. These methods are overridden in order to modify the 
behavior defined by an ancestor class. 

• somlnit 

• somUninit 

• somDumpSelf 

• somDumpSelflnt 

• describe 



InterfaceDef 



File stem: intfacdf 
Base 

Contained 

Container 

Metaclass 



SOMCIass 




Ancestor Classes 
Contained 

Container 

SOMObject 

Description 

Types 



struct FullInterfaceDescription { 

Identifier name; 

Repositoryld id; 

Repositoryld defined_in; 

sequence<OperationDef : : OperationDescription> operation; 
sequence<AttributeDef : : AttributeDescription> attributes; 

} ; 



struct Interf aceDescription { 

Identifier name; 
Repositoryld id; 
Repositoryld defined_in; 



The describe method, inherited from Contained, returns an InterfaceDescription structure in the "value" member of the Description 
structure (defined in the Contained class). The describe_contents method, inherited from Container, returns a sequence of these 
Description structures, each carrying a reference to an InterfaceDescription structure in its "value" member. 

Implementation note The two sequences "Operation Description" and "AttributeDescription" are built dynamically within the 
FullInterfaceDescription structure, due to the InterfaceDef class's inheritance from the Contained class. 

Attributes 

All attributes of the InterfaceDef class provide access to information kept within the receiving InterfaceDef object. The "_get_" form of the 
attribute returns a memory reference that is only valid as long as the receiving object has not been freed (using _somFree). The "_set_” 
form of the attribute makes a (deep) copy of your data and places it in the receiving InterfaceDef object. You retain ownership of all memory 
references passed using the "_set_" attribute forms. 

Listed below is each available attribute, with its corresponding type in parentheses, followed by a description of its purpose: 
basejnterfaces (sequence <Repositoryld>) 

The sequence of Repositorylds for all of the interfaces that the receiving interface inherits. 
instanceData (TypeCode) 

The TypeCode of a structure whose members are the internal instance variables, if any, described in the SOM implementation 
section of the interface. 

Note: This attribute is a SOM-unique extension of the Interface Repository; it is not stipulated by the CORBA specifications. 

New methods 

The following list shows all the InterfaceDef methods. 

• describejnterface 

Overridden methods 

The following list shows all the methods overridden by the InterfaceDef class. These methods are overridden in order to modify the behavior 
defined by an ancestor class. 

• somlnit 

• somUninit 

• somDumpSelf 

• somDumpSelflnt 

• within 

• describe 



describe interface 




describejnterface - Syntax 



This method returns (from the Interface Repository) a description of all the methods and attributes of an interface definition. 



InterfaceDef receiver; 

Environment *env; 

Fulllnterf aceDescription rc; 

rc = describe_interf ace (receiver, env) ; 



describe interface Parameter - receiver 



receiver (InterfaceDef) 

A pointer to an object of class InterfaceDef representing the Interface Repository object where an interface definition is stored. 



describe interface Parameter - env 



env (Environment *) 

A pointer where the method can return exception information if an error is encountered. 



describe interface Parameter - rc 



rc (FullInterfaceDescription) 

Returns a description of all the methods and attributes of an interface definition that are held in the Interface Repository. 



describe interface - Parameters 



receiver (InterfaceDef) 

A pointer to an object of class InterfaceDef representing the Interface Repository object where an interface definition is stored, 
env (Environment *) 

A pointer where the method can return exception information if an error is encountered. 



rc (FullInterfaceDescription) 

Returns a description of all the methods and attributes of an interface definition that are held in the Interface Repository. 



describe interface - Remarks 



The describejnterface method returns a description of all the methods and attributes of an interface definition that are held in the Interface 
Repository. 

When finished using the FullInterfaceDescription returned by this method, the client code is responsible for freeing the _buffer fields of the 
two sequences it contains. In C, this can be accomplished as follows: 

if (fid. operation ._length) 



SOMFree ( fid . operation ._buffer) ; 


/* 


Release 


the 


buffer 


*/ 


(fid. attributes ._length) 

SOMFree ( fid . attributes ._buffer) ; 


/* 


Release 


the 


buffer 


*/ 



describejnterface - Original Class 



InterfaceDef 



describejnterface - Example Code 



#include <intfacdf.h> 



InterfaceDef idef; 

Environment *ev; 
FullInterfaceDescription fid; 
long i; 



fid = InterfaceDef_describe_interface (idef, ev) ; 
printf ("The %s interface has the following 
attributes : \n" , 

Contained get_name ( (Contained) idef, ev) ) ; 

if (! fid. attributes ._length) 
printf ( "\t [none] \n" ) ; 
else { 

for (i=0; i <f id . attributes ._length; i++) { 

printf ("\t%s\n", 
fid. attributes ._buffer [i] .name) ; 

SOMFree ( fid . attributes ._buffer) ; 

} 

printf ("and the following methods :\n") 
if (! fid . operation ._length) 
printf ( "\t [none] \n" ) ; 
else { 

for (i=0; i <f id . attributes ._length; i++) { 

printf ("\t%s\n", f id . operation ._buffer [ i ]. name) ; 
SOMFree ( fid . operation ._buffer) ; 




describe Jnterface - Topics 



Select an item: 
Syntax 
Parameters 
Returns 
Remarks 
Original Class 
Example Code 
Glossary 



ModuleDef 



File stem: moduledf 
Base 

Contained 

Container 

Metaclass 

SOMCIass 

Ancestor Classes 
Contained 

Container 

SOMObject 

Description 

Types 



struct ModuleDescription { 

Identifier name; 
Repositoryld id; 
Repositoryld defined_in; 

} ; 



The describe method, inherited from Contained, returns a ModuleDescription structure in the "value" member of the Description 
structure (defined in the Contained class). The describe_contents method, inherited from Container, returns a sequence of these 
Description structures, each carrying a reference to a ModuleDescription structure in its "value" member. 

New methods 

There are currently no new methods defined for the ModuleDef class. 

Overridden methods 

The following list shows all the methods overridden by the ModuleDef class. These methods are overridden in order to modify the behavior 
defined by an ancestor class. 

• somlnit 

• somUninit 

• somDumpSelf 

• somDumpSelflnt 

• describe 



within 



Operation Def 



File stem: operatdf 
Base 



Contained 

Container 

Metaclass 

SOMCIass 



Ancestor Classes 
Contained 

Container 

SOMObject 

Description 

Types 

typedef Identifier Contextldentifier ; 
enum OperationMode { NORMAL, ONEWAY }; 



struct OperationDescription { 

Identifier name; 

Repositoryld id; 

Repositoryld defined_in; 

TypeCode result; 

OperationMode mode; 

sequence <ContextIdentif ier> contexts; 
sequence <ParameterDef : : ParameterDescription> 
sequence < ExceptionDef : : ExceptionDescription> 



parameter; 

exceptions; 



The describe method, inherited from Contained, returns an OperationDescription structure in the "value" member of the Description 
structure (defined in the Contained class). The describe_contents method, inherited from Container, returns a sequence of these 
Description structures, each carrying a reference to an OperationDescription structure in its "value" member. 

Attributes 



Listed below is each available attribute, with its corresponding type in parentheses, followed by a description of its purpose: 



result (TypeCode) 

The TypeCode that represents the type of the operation (method). The TypeCode returned by the "_get_" form of the type 
attribute is contained in the receiving OperationDef object, which retains ownership. Hence, the returned TypeCode should not be 
freed. To obtain a separate copy, use the TypeCode_copy operation. The "_set_" form of the attribute makes a private copy of the 
TypeCode you supply, to keep in the receiving object. You retain ownership of the passed TypeCode. 



mode (OperationMode) 

The OperationMode of the operation (method), either NORMAL or ONEWAY. 



contexts (sequence <Contextldentifier>) 

The list of Contextldentifiers associated with the operation (method). The ”_get_" form of the attribute returns a sequence whose 
buffer is owned by the receiving OperationDef object. You should not free it. The ”_set_" form of the attribute makes a (deep) copy 
of the passed sequence; you retain ownership of the original storage. 



New methods 



There are currently no new methods defined for the OperationDef class. 



Overridden methods 




The following list shows all the methods overridden by the OperationDef class. These methods are overridden in order to modify the 
behavior defined by an ancestor class. 

• somlnit 

• somUninit 

• somDumpSelf 

• somDumpSelflnt 

• describe 



ParameterDef 



File stem: paramdef 

Base 

Contained 

Metaclass 

SOMCIass 

Ancestor Classes 
Contained 

SOMObject 

Description 

Types 

enum ParameterMode { IN, OUT, INOUT }; 

struct ParameterDescription { 

Identifier name; 

Repository-Id id; 

Repositoryld defined_in; 

TypeCode type; 

ParameterMode mode; 

} ; 



The describe method, inherited from Contained, returns a ParameterDescription structure in the "value" member of the Description 
structure (defined in the Contained class). 

Attributes 

Listed below is each available attribute, with its corresponding type in parentheses, followed by a description of its purpose: 
type (TypeCode) 

The TypeCode that represents the type of the parameter. The TypeCode returned by the "_get_" form of the type attribute is 
contained in the receiving ParameterDef object, which retains ownership. Hence, the returned TypeCode should not be freed. To 
obtain a separate copy, use the TypeCode_copy operation. The "_set_” form of the attribute makes a private copy of the 
TypeCode you supply, to keep in the receiving object. You retain ownership of the passed TypeCode. 

mode (ParameterMode) 

The ParameterMode of the parameter (IN, OUT, or INOUT). 

New methods 

There are currently no new methods defined for the ParameterDef class. 

Overridden methods 

The following list shows all the methods overridden by the ParameterDef class. These methods are overridden in order to modify the 
behavior defined by an ancestor class. 



somlnit 




somUninit 

somDumpSelf 

somDumpSelflnt 

describe 



Repository 



File stem: repostry 
Base 
Container 
Metaclass 

SOMCIass 

Ancestor Classes 
Container 

SOMObject 

Description 

Types 

struct RepositoryDescription { 

Identifier name; 
Repositoryld id; 
Repositoryld defined_in; 

}; 



The inherited describe_contents method returns an instance of the RepositoryDescription structure in the "value" member of the 
Description structure defined in the Container interface. 

New methods 

The following list shows all the Repository methods. 

• lookupjd 

• lookup_modifier 

• release_cache 

Overridden methods 

The following list shows all the methods overridden by the Repository class. These methods are overridden in order to modify the behavior 
defined by an ancestor class. 

• describe_contents 

• somlnit 

• somUninit 

• somFree 

• somDumpSelf 

• somDumpSelflnt 



lookupjd 




lookupjd - Syntax 



This method returns the object having a specified Repositoryld. 



Repository 

Environment 

Repositoryld 

Contained 



receiver; 

*env; 

search_id; 

rc; 



rc = lookup_id (receiver, env, search_id) ; 



lookupjd Parameter - receiver 



receiver (Repository) 

A pointer to an object of class Repository representing SOM's Interface Repository. 



lookupjd Parameter - env 



env (Environment *) 

A pointer where the method can return exception information if an error is encountered. 



lookupjd Parameter - search id 



searchjd (Repositoryld) 

An ID value of type Repositoryld that uniquely identifies the desired object in the Interface Repository. 



lookupjd Parameter - rc 



rc (Contained) 

Returns the Contained object that has the specified Repositoryld. 



lookupjd - Parameters 



receiver (Repository) 

A pointer to an object of class Repository representing SOM's Interface Repository, 
env (Environment *) 

A pointer where the method can return exception information if an error is encountered, 
searchjd (Repositoryld) 

An ID value of type Repositoryld that uniquely identifies the desired object in the Interface Repository, 
rc (Contained) 

Returns the Contained object that has the specified Repositoryld. 



lookupjd - Remarks 



The lookupjd method returns the object having a Repositoryld given by the specified searched argument. The returned object 
represents a component of an IDL interface (class) definition maintained within the Interface Repository. 

When finished using the object returned by this method, the client code is responsible for releasing it, using the somFree method. 



lookupjd - Original Class 

Repository 



lookupjd - Related Methods 



Methods 



lookupmodifier 

lookupname 

contents 

within 



lookupjd - Example Code 



#include <containd.h> 
#include <repostry.h> 



Repository repo; 
Environment *ev; 

Contained c; 

Repositoryld ob jectToFind; 




repo = RepositoryNew (); 

c = Repository_lookup_id (repo, ev, ob jectToFind) ; 
if (c) { 

printf ("lookup_id found object of type: %s, named: %s\n", 

SOMOb ject_somGetClassName (c) , Contained get_name (c, ev) ) ; 

SOMOb ject_somFree (c) ; 

} 



lookup Jd - Topics 



Select an item: 
Syntax 
Parameters 
Returns 
Remarks 
Original Class 
Example Code 
Related Methods 
Glossary 



lookup_modifier 



lookup_modifier - Syntax 



Returns the value of a given SOM modifier for a specified object [that is, for an object that is a component of an IDL interface (class) 
definition maintained within the Interface Repository], 



Repository 

Environment 

Repositoryld 

string 

string 



receiver; 

*env; 

id; 

modifier; 

rc; 



rc = lookup_modif ier (receiver, env, id, 
modifier) ; 



lookup_modifier Parameter - receiver 



receiver (Repository) 

A pointer to an object of class Repository representing SOM's Interface Repository. 



lookup_modifier Parameter - env 



env (Environment *) 

A pointer where the method can return exception information if an error is encountered. 



lookup_modifier Parameter - id 



id (Repositoryld) 

The Repositoryld of the object whose modifier value is needed. 



lookup_modifier Parameter - modifier 

modifier (string) 

The name of a specific (SOM or user-specified) modifier whose string value is needed. 



lookup_modifier Parameter - rc 



rc (string) 

The lookup_modifier method returns the string value of the given SOM modifier for an object with the specified Repositoryld, if it 
exists. If an existing modifier has no value, a zero-length string value is returned. If the object cannot be found, then NULL (or zero) is 
returned. 

When the string value is no longer needed, client code must free the space for the string (using SOMFree). 



lookup_modifier - Parameters 



receiver (Repository) 

A pointer to an object of class Repository representing SOM's Interface Repository, 
env (Environment *) 

A pointer where the method can return exception information if an error is encountered, 
id (Repositoryld) 

The Repositoryld of the object whose modifier value is needed, 
modifier (string) 

The name of a specific (SOM or user-specified) modifier whose string value is needed. 



rc (string) 




The lookup_modifier method returns the string value of the given SOM modifier for an object with the specified Repositoryld, if it 
exists. If an existing modifier has no value, a zero-length string value is returned. If the object cannot be found, then NULL (or zero) is 
returned. 

When the string value is no longer needed, client code must free the space for the string (using SOMFree). 



lookup_modifier - Remarks 



The lookup_modifier method returns the string value of the given SOM modifier for an object with the specified Repositoryld within the 
Interface Repository. For a discussion of SOM modifiers, see the topic "Modifier statements" in Chapter 4, "SOM IDL and The SOM 
Compiler,” of the SOM Too/k/t User's Guide . 

If the object with the given Repositoryld does not exist or does not possess the modifier, then NULL (or zero) is returned. If the object exists 
but the specified modifier does not have a value, a zero-length string value is returned. 

Note: The lookup_modifier method is not stipulated by the CORBA specifications; it is a SOM-unique extension to the Interface 
Repository. 



lookup_modifier - Original Class 



Repository 



lookup_modifier - Related Methods 



Methods 



lookupjd 

lookupname 



lookup_modifier - Example Code 



#include <repostry.h> 



Repository repo; 
Environment *ev; 
Repositoryld objectld; 
string filestem;i 



repo = RepositoryNew (); 

filestem = Repository_lookup_modif ier (repo, ev, objectld, 

"f ilestem" ) ; 

if (filestem) { 
printf 

("The %s object's filestem modifier has the value \"%s\"\n", 




objectld, filestem) ; 

SOMFree (filestem) ; 

} else 

printf ("No filestem modifier could be found for %s\n", 
objectld) ; 



lookup_modifier - Topics 



Select an item: 
Syntax 
Parameters 
Returns 
Remarks 
Original Class 
Example Code 
Related Methods 
Glossary 



release cache 



release_cache - Syntax 



This method permits the Repository object to release the memory occupied by Interface Repository objects that have been implicitly 
referenced. 



Repository receiver; 

Environment *env; 

release_cache (receiver, env) ; 



release cache Parameter - receiver 



receiver (Repository) 

A pointer to an object of class Repository representing SOM's Interface Repository. 



release cache Parameter - env 



env (Environment *) 

A pointer where the method can return exception information if an error is encountered. 



release cache Parameter - rc 



rc 



release cache - Parameters 



receiver (Repository) 

A pointer to an object of class Repository representing SOM's Interface Repository, 
env (Environment *) 

A pointer where the method can return exception information if an error is encountered. 



rc 



release cache - Remarks 



This method allows the Repository object to release the memory occupied by implicitly referenced Interface Repository objects. Some 
methods (such as describe_contents and lookup_name) may cause some objects to be instantiated that are not directly accessible 
through object references that have been returned to the user. These objects are kept in an internal Interface Repository cache until the 
release_cache method is used to free them. The internal cache continuously replenishes itself over time as the need arises. 

See the section entitled "A word about memory management" in the Interface Repository Framework in the SOM Too/k/t User's Guide . 



release_cache - Original Class 

Repository 



release_cache - Example Code 



#include <repostry.h> 



Repository repo; 
Environment *ev; 




sequence (ContainerDescription) scd; 



scd = Container_describe_contents ( 

(Container) repo, ev, "TypeDef", TRUE, -T) ; 

Repository_release_cache (repo, ev) ; 



release_cache - Topics 



Select an item: 
Syntax 
Parameters 
Returns 
Remarks 
Original Class 
Example Code 
Glossary 



TypeDef 



File stem: typedef 
Base 
Contained 
Metaclass 

SOMCIass 



Ancestor Classes 
Contained 

SOMObject 

Description 



Types 



struct TypeDescription 



Identifier 
Repositoryld 
Repositoryld 
TypeCode 
} ; 



name ; 
id; 

def ined_in; 
type; 



{ 



The describe method, inherited from Contained, returns a TypeDescription structure in the ''value” member of the Description structure 
(defined in the Contained class). 

Attributes 

Listed below is each available attribute, with its corresponding type in parentheses, followed by a description of its purpose: 
type (TypeCode) 

The TypeCode that represents the type of the typedef. The TypeCode returned by the "_get_" form of the type attribute is 
contained in the receiving TypeDef object, which retains ownership. Hence, the returned TypeCode should not be freed. To obtain 
a separate copy, use the TypeCode_copy operation. The "_set_” form of the attribute makes a private copy of the TypeCode you 
supply, to keep in the receiving object. You retain ownership of the passed TypeCode. 



New methods 



There are currently no new methods defined for the TypeDef class. 

Overridden methods 

The following list shows all the methods overridden by the TypeDef class. These methods are overridden in order to modify the behavior 
defined by an ancestor class. 

■ somlnit 

• somUninit 

■ somDumpSelf 

• somDumpSelflnt 

• describe 



TypeCode_alignment 



TypeCode_alignment - Syntax 



This function supplies the alignment value for a given TypeCode. 



TypeCode tc; 

Environment *env; 

short rc; 

rc = TypeCode_alignment (tc, env) ; 



TypeCode_alignment Parameter - tc 



tc (TypeCode) 

The TypeCode whose alignment information is desired. 



TypeCode_alignment Parameter - env 



env (Environment *) 

A pointer to an Environment structure. 



TypeCode_alignment Parameter - rc 



rc (short) 

A short integer containing the alignment value. 



TypeCode_alignment - Parameters 



tc (TypeCode) 

The TypeCode whose alignment information is desired. 

env (Environment *) 

A pointer to an Environment structure. 

rc (short) 

A short integer containing the alignment value. 



TypeCode_alignment - Remarks 



This function returns the alignment information associated with the given TypeCode. The alignment value is a short integer that should 
evenly divide any memory address where an instance of the type described by the TypeCode will occur. 



TypeCode_alignment - Related Information 



Functions 



• TypeCodeNew 

• TypeCode_equal 

• TypeCode_kind 

• TypeCode_param_count 

• TypeCode_parameter 

• TypeCode_setAlignment 

• TypeCode_size 

• TypeCode_free 

• TypeCode_print 



TypeCode_alignment - Topics 



Select an item: 

Syntax 

Parameters 

Returns 

Remarks 

Related Information 
Glossary 



TypeCode_copy 



TypeCode_copy - Syntax 



This function creates a new copy of a given TypeCode. 



TypeCode tc; 

Environment *env; 

TypeCode rc; 

rc = TypeCode_copy (tc, env); 



TypeCode_copy Parameter - tc 



tc (TypeCode) 

The TypeCode to be copied. 



TypeCode_copy Parameter - env 



env (Environment *) 

A pointer to an Environment structure. The CORBA standard mandates the use of this structure as a standard way to return 
exception information when an error condition is detected. 



TypeCode_copy Parameter - rc 



rc (TypeCode) 

A new TypeCode with no internal references to any previously existing TypeCodes or strings. If a copy cannot be created 
successfully, the value NULL is returned. No exceptions are raised by this function. 



TypeCode_copy - Parameters 



tc (TypeCode) 

The TypeCode to be copied. 



env (Environment *) 

A pointer to an Environment structure. The CORBA standard mandates the use of this structure as a standard way to return 
exception information when an error condition is detected. 



rc (TypeCode) 

A new TypeCode with no internal references to any previously existing TypeCodes or strings. If a copy cannot be created 
successfully, the value NULL is returned. No exceptions are raised by this function. 



TypeCode_copy - Remarks 



The TypeCode_copy function creates a new copy of a given TypeCode. TypeCodes are complex data structures whose actual 
representation is hidden and may contain internal references to strings and other TypeCodes. The copy created by this function is 
guaranteed not to refer to any previously existing TypeCodes or strings, and hence can be used long after the original TypeCode is freed 
or released (TypeCodes are typically contained in Interface Repository objects whose memory resources are released by the _somFree 
method). 

All of the memory used to construct the TypeCode copy is allocated dynamically and should be subsequently freed on/y by using the 

TypeCode_free function. 

This function is a SOM-unique extension to the CORBA standard. 



TypeCode_copy - Related Information 



Functions 



• TypeCodeNew 

• TypeCode_alignment 

• TypeCode_equal 

• TypeCode_kind 

• TypeCode_param_count 

• TypeCode_parameter 

• TypeCode_size 

• TypeCode_free 

• TypeCode_print 

• TypeCode_setAlignment 



TypeCode_copy - Topics 



Select an item: 

Syntax 

Parameters 

Returns 

Remarks 

Related Information 
Glossary 



TypeCode_equal 



TypeCode_equal - Syntax 



This function compares two TypeCodes for equality. 



TypeCode tc; 

Environment *env; 

TypeCode tc2; 

boolean rc; 



rc = TypeCode_equal (tc, env, tc2); 



TypeCode_equal Parameter - tc 



tc (TypeCode) 

One of the TypeCodes to be compared. 



TypeCode_equal Parameter - env 



env (Environment *) 

A pointer to an Environment structure. The CORBA standard mandates the use of this structure as a standard way to return 
exception information when an error condition is detected. 



TypeCode_equal Parameter - tc2 



tc2 (TypeCode) 

The other TypeCode to be compared. 



TypeCode_equal Parameter - rc 



rc (boolean) 

Returns TRUE (1) if the TypeCodes tc and tc2 describe the same data type, with the same alignment. Otherwise, FALSE (0) 
returned. No exceptions are raised by this function. 



TypeCode_equal - Parameters 



tc (TypeCode) 

One of the TypeCodes to be compared. 



env (Environment *) 

A pointer to an Environment structure. The CORBA standard mandates the use of this structure as a standard way to return 
exception information when an error condition is detected. 



tc2 (TypeCode) 

The other TypeCode to be compared. 



rc (boolean) 

Returns TRUE (1) if the TypeCodes tc and tc2 describe the same data type, with the same alignment. Otherwise, FALSE (0) 
returned. No exceptions are raised by this function. 



TypeCode_equal - Remarks 



The TypeCode_equal function can be used to determine if two distinct TypeCodes describe the same underlying abstract data type. 



TypeCode_equal - Related Information 



Functions 

• TypeCodeNew 

• TypeCode_alignment 

• TypeCode_kind 

• TypeCode_param_count 

• TypeCode_parameter 

• TypeCode_copy 

• TypeCode_free 

• TypeCode_print 

• TypeCode_setAlignment 

• TypeCode_size 



TypeCode_equal - Topics 



Select an item: 

Syntax 

Parameters 

Returns 

Remarks 

Related Information 
Glossary 



TypeCode_free 



TypeCode_free - Syntax 



This function destroys a given TypeCode by freeing all of the memory used to represent it. 



TypeCode tc; 

Environment *env; 

TypeCode_f ree (tc, env) ; 



TypeCode_free Parameter - tc 



tc (TypeCode) 

The TypeCode to be freed. 



TypeCode_free Parameter - env 



env (Environment *) 

A pointer to an Environment structure. The CORBA standard mandates the use of this structure as a standard way to return 
exception information when an error condition is detected. 



TypeCode_free Parameter - rc 



rc 



TypeCode_free - Parameters 



tc (TypeCode) 

The TypeCode to be freed. 



env (Environment *) 

A pointer to an Environment structure. The CORBA standard mandates the use of this structure as a standard way to return 
exception information when an error condition is detected. 



rc 



TypeCode_free - Remarks 



The TypeCode_free function destroys a given TypeCode by freeing all of the memory used to represent it. TypeCodes obtained from the 
TypeCode_copy or TypeCodeNew functions should be freed using TypeCode_free. TypeCodes contained in Interface Repository objects 
should never be freed. Their memory is released when a _somFree method releases the Interface Repository object. 

The TypeCode_free operation has no effect on TypeCode constants. TypeCode constants are static TypeCodes declared in the header 
file "somtcnst.h" or generated in files emitted by the SOM Compiler. Since TypeCode constants may be used interchangeably with 
dynamically created TypeCodes, it is not considered an error to attempt to free a TypeCode constant with the TypeCode_free function. 

This function is a SOM-unique extension to the CORBA standard. 



TypeCode_free - Related Information 



Functions 



• TypeCodeNew 

• TypeCode_alignment 

• TypeCode_equal 

• TypeCode_kind 

• TypeCode_param_count 

• TypeCode_parameter 

• TypeCode_size 

• TypeCode_copy 

• TypeCode_print 

• TypeCode_setAlignment 



TypeCode_free - Topics 



Select an item: 

Syntax 

Parameters 

Returns 

Remarks 

Related Information 
Glossary 



TypeCode_kind 



TypeCode_kind - Syntax 



This function categorizes the abstract data type described by a TypeCode. 



TypeCode tc; 

Environment *env; 

TCKind rc; 

rc = TypeCode_kind (tc, env) ; 



TypeCode_kind Parameter - tc 



tc (TypeCode) 

The TypeCode whose TCKind categorization is requested. 



TypeCode_kind Parameter - env 



env (Environment *) 

A pointer to an Environment structure. 



The CORBA standard mandates the use of this structure as a standard way to return exception information when an error condition is 
detected. 



TypeCode_kind Parameter - rc 



rc (TCKind) 

Returns one of the enumerators listed in the TCKind enumeration shown below. No exceptions are raised by this function, enum 
TCKind { tk_null, tk_void, tk_short, tkjong, tk_ushort, tk_ulong, tk_float, tk_double, tk_boolean, tk_char, tk_octet, 

tk_any, tk_TypeCode, tk_Principal, tk_objref, tk_struct, tk_union, tk_enum, tk_string, tk_sequence, tk_array, 

tk_pointer, tk_self, tkjoreign }; 



TypeCode_kind - Parameters 



tc (TypeCode) 

The TypeCode whose TCKind categorization is requested. 



env (Environment *) 



A pointer to an Environment structure. 



The CORBA standard mandates the use of this structure as a standard way to return exception information when an error condition is 
detected. 

rc (TCKind) 

Returns one of the enumerators listed in the TCKind enumeration shown below. No exceptions are raised by this function, enum 
TCKind { tk_null, tk_void, tk_short, tkjong, tk_ushort, tk_ulong, tk_float, tk_double, tk_boolean, tk_char, tk_octet, 

tk_any, tk_TypeCode, tk_Principal, tk_objref, tk_struct, tk_union, tk_enum, tk_string, tk_sequence, tk_array, 

tk_pointer, tk_self, tkjoreign }; 



TypeCode_kind - Remarks 



The TypeCode_kind function can be used to classify a TypeCode into one of the categories listed in the TCKind enumeration. Based on 
the "kind" classification, a TypeCode may contain 0 or more additional parameters to fully describe the underlying data type. 

The following table indicates the number and function of these additional parameters. TCKind entries not listed in the table are basic data 
types and do not have any additional parameters. The designation "N" refers to the number of members in a struct or union, or the number 
of enumerators in an enum. 



TypeCode information per TCKind category 



TCKIND 


PARAMETERS 


TYPE 


FUNCTION 


TK_ 


_OB JREF 


1 


STRING 


The ID of the corresponding INTERFACED 
Repository 


TK_ 


.STRUCT 


2N+1 


STRING 


The name of the STRUCT. 










next 2 repeat for each memt 








STRING 

TYPECODE 


The name of the STRUCT member. 
The type of the STRUCT member. 


TK_ 


.UNION 


3N+2 


STRING 

TYPECODE 


The name of the UNION. 

The type of the discriminator. 










next 3 repeat for each memt 








LONG 

STRING 

TYPECODE 


The label value 

The name of the member. 

The type of the member. 


TK_ 


.ENUM 


N+l 


STRING 


The name of the ENUM. 










next repeats for each enumera 








STRING 


The name of the enumerator. 


TK_ 


.STRING 


1 


LONG 


The maximum string length or 0. 


TK_ 


.SEQUENCE 


2 


TYPECODE 

LONG 


The type of element in the sequence. 
The maximum number of elements or 0. 


TK_ 


.ARRAY 


2 


TYPECODE 

LONG 


The type of element in the ARRAY. 
The maximum number of elements. 


TK_ 


.POINTER* 


1 


TYPECODE 


The type of the referenced datum. 


TK_ 


.SELF* 


1 


STRING 


The name of the referenced enclosing ST 




TK_FOREIGN* 



3 



STRING 

STRING 

LONG 



The name of the foreign type. 
The implementation context. 
The size of an instance. 



* The TCKIND values TK_POINTER, TK_SELF, and TK_FOREIGN are SOM-unique extensions to th 
provided to permit TYPECODES to describe types that cannot be expressed in standard IDI 

The TK_POINTER TYPECODE contains only one parameter-a TYPECODE which describes the data 
ences . The TK_SELF TYPECODE is used to describe a "self-referential" structure or union 
unbounded recursion in the TYPECODE. For example, the following C struct: 

struct node { 
long count; 
struct node *next; 

} ; 



could be described with a TYPECODE created as follows: 

TypeCode tcForNode; 

tcForNode = TypeCodeNew (tk_struct, "node", 

"count", TypeCodeNew (tk_long) , 

"next", TypeCodeNew (tk_pointer, 

TypeCodeNew (tk_self, "node"))); 

The TK_FOREIGN TYPECODE provides a more general escape mechanism, allowing TYPECODEs tc 
describe non-IDL types. Since these foreign TYPECODEs carry only a partial description 
tion context" parameter can be used by a non-IDL execution environment to recognize otl 
understood in that environment. See the section entitled "Using the tk_foreign TypeCode 
Toolkit User's Guide for more information about using foreign TYPECODES in SOM IDL file 

Note that the use of self-referential structures, pointers, or foreign types is beyond 
standard, and may result in a loss of portability or distributability in client code. 



TypeCode_kind - Original Class 



TypeDef 



TypeCode_kind - Related Information 



Functions: 



• TypeCodeNew 

• TypeCode_alignment 

• TypeCode_equal 

• TypeCode_param_count 

• TypeCode_parameter 

• TypeCode_copy 

• TypeCode_free 

• TypeCode_print 

• TypeCode_setAlignment 

• TypeCode_size 




TypeCode_kind - Topics 



Select an item: 
Syntax 
Parameters 
Returns 
Remarks 
Original Class 
Related Information 
Glossary 



TypeCodeNew 



TypeCodeNew - Syntax 



This function creates a new TypeCode instance. 



rc = TypeCodeNew (tag, interfacelD, name, mbrName, 
Enumld, structOrUnionName, maxLength, 
length, flag, labelValue, mbrTC, swTC, 
seqTC, arrayTC, ptrTC, typename, impCtx, 
instSize, allOtherTagValues) ; 



TypeCodeNew Parameter - tag 



TCKind 

string 

string 

string 

string 

string 

long 

long 

long 

long 

TypeCode 

TypeCode 

TypeCode 

TypeCode 

TypeCode 

string 

string 

long 

TCKind 

TypeCode 



tag; 

interfacelD; 
name ; 
mbrName; 

Enumld; 

StructOrUnionName; 

maxLength; 

length; 

flag; 

labelValue; 

mbrTC; 

swTC ; 

seqTC; 

arrayTC; 

ptrTC; 

typename; 

impCtx; 

instSize; 

allOtherTagValues; 

rc; 



tag (TCKind) 



The type or category of TypeCode to create. The actual parameters that follow are variable in number and type, depending on the 
value of the tag paramater. (There are no implicit parameters in this function.) See the remarks section for the syntax form 
appropriate for each kind of TCKind tag. 



TypeCodeNew Parameter - interfacelD 



interfacelD (string) 

A string containing the fully-qualified interface name that is the subject of an object reference type. 



TypeCodeNew Parameter - name 



name (string) 

A string that gives the name of a struct, union, or enum. 



TypeCodeNew Parameter - mbrName 



mbrName (string) 

A string that gives the name of a struct or union member element. 



TypeCodeNew Parameter - Enumld 



Enumld (string) 

A string that gives the name of an enum enumerator. 



TypeCodeNew Parameter - structOrUnionName 



structOrUnionName (string) 

A string that gives the name of a struct or union that has been previously named in the current TypeCode and is the subject of a 
self-referential pointer type. See the footnote on tk_self in Table 1 for an example of what this means and how it is applied. 



TypeCodeNew Parameter - maxLength 




maxLength (long) 

The maximum permitted length of a string or a sequence. The value 0 (zero) means that the string or sequence is considered 
unbounded. 



TypeCodeNew Parameter - length 



length (long) 

The maximum number of elements that can be stored in an array. All IDL arrays are bounded, hence a value of zero denotes an 
array of zero elements. 



TypeCodeNew Parameter - flag 



flag (long) 

One of the following constant values used to distinguish a labeled case in an IDL discriminated union switch statement from the 
default case: 

TCREGULAR_CASE - The value 1 
TCDEFAULT_CASE - The value 2 



TypeCodeNew Parameter - labelValue 



labelValue (long) 

The actual value associated with a regular labeled case in an IDL discriminated union switch statement. If preceded by the argument 
TCDEFAULT_CASE, the value zero should be used. 



TypeCodeNew Parameter - mbrTC 



mbrTC (TypeCode) 

A TypeCode that represents the data type of a struct or union member. 



TypeCodeNew Parameter - swTC 



swTC (TypeCode) 




A TypeCode that represents the data type of the discriminator in an IDL union statement. 



TypeCodeNew Parameter - seqTC 



seqTC (TypeCode) 

A TypeCode that describes the data type of the elements in a sequence. 



TypeCodeNew Parameter - arrayTC 



arrayTC (TypeCode) 

A TypeCode that describes the data type of the elements of an array. 



TypeCodeNew Parameter - ptrTC 



ptrTC (TypeCode) 

A TypeCode that describes the data type referenced by a pointer. 



TypeCodeNew Parameter - typename 



typename (string) 

A string that provides the name of a foreign type. 



TypeCodeNew Parameter - impCtx 



impCtx (string) 

A string that identifies an implementation context where a foreign type is understood. 



TypeCodeNew Parameter - instSize 




instSize (long) 

A long that holds the size of a foreign type instance. If the size is variable or is not known, the value zero should be used. 



TypeCodeNew Parameter - allOtherTagValues 



allOtherTagValues (TCKind) 

One of the values: tknull, tkvoid, tkshort, tklong, tkushort, tkulong, tkfloat, tkdouble, tkboolean, tkchar, tkoctet, 
tk_any, tk_TypeCode, or Tk_Principal. All of these tags represent basic IDL data types that do not require any other descriptive 
parameters. 



TypeCodeNew Parameter - rc 

rc (TypeCode) 

A new TypeCode instance, or NULL if the new instance could not be created. 



TypeCodeNew - Parameters 



tag (TCKind) 

The type or category of TypeCode to create. The actual parameters that follow are variable in number and type, depending on the 
value of the tag paramater. (There are no implicit parameters in this function.) See the remarks section for the syntax form 
appropriate for each kind of TCKind tag. 

interfacelD (string) 

A string containing the fully-qualified interface name that is the subject of an object reference type, 
name (string) 

A string that gives the name of a struct, union, or enum. 
mbrName (string) 

A string that gives the name of a struct or union member element. 

Enumld (string) 

A string that gives the name of an enum enumerator. 

structOrUnionName (string) 

A string that gives the name of a struct or union that has been previously named in the current TypeCode and is the subject of a 
self-referential pointer type. See the footnote on tk_self in Table 1 for an example of what this means and how it is applied. 

maxLength (long) 

The maximum permitted length of a string or a sequence. The value 0 (zero) means that the string or sequence is considered 
unbounded. 



length (long) 

The maximum number of elements that can be stored in an array. All IDL arrays are bounded, hence a value of zero denotes an 
array of zero elements. 

flag (long) 

One of the following constant values used to distinguish a labeled case in an IDL discriminated union switch statement from the 
default case: 

TCREGULAR_CASE - The value 1 
TCDEFAULT_CASE - The value 2 




labelValue (long) 

The actual value associated with a regular labeled case in an IDL discriminated union switch statement. If preceded by the argument 
TCDEFAULT_CASE, the value zero should be used. 

mbrTC (TypeCode) 

A TypeCode that represents the data type of a struct or union member. 
swTC (TypeCode) 

A TypeCode that represents the data type of the discriminator in an IDL union statement. 
seqTC (TypeCode) 

A TypeCode that describes the data type of the elements in a sequence. 
arrayTC (TypeCode) 

A TypeCode that describes the data type of the elements of an array. 
ptrTC (TypeCode) 

A TypeCode that describes the data type referenced by a pointer, 
typename (string) 

A string that provides the name of a foreign type. 
impCtx (string) 

A string that identifies an implementation context where a foreign type is understood. 

instSize (long) 

A long that holds the size of a foreign type instance. If the size is variable or is not known, the value zero should be used. 

allOtherTagValues (TCKind) 

One of the values: tk null, tk void, tk short, tk long, tkushort, tk ulong, tk float, tk double, tkboolean, tk char, tkoctet, 
tk_any, tk_TypeCode, or Tk_Principal. All of these tags represent basic IDL data types that do not require any other descriptive 
parameters. 

rc (TypeCode) 

A new TypeCode instance, or NULL if the new instance could not be created. 



TypeCodeNew - Remarks 



The TypeCodeNew function creates a new instance of a TypeCode from the supplied parameters. TypeCodes are complex data structures 
whose actual representation is hidden. The number and types of arguments required by TypeCodeNew varies depending on the value of 
the first argument. The syntax for all of the valid invocation sequences are as follows: 

TyepCodeNew(tk_objref, string interfaceld): 

TypeCodeNew(tk_string, long maxLength); 

TypeCodeNew(tk_sequence, TypeCode seqTC, long maxLength); 

TypeCodeNew(tk_array, TypeCodearrayTC, long length); 

TypeCodeNew(tk_pointer, TypeCode ptrTC); 

TypeCodeNew(tk_self, string structOrUnionName); 

TypeCodeNew(tk_foreign, string typename, string impCtx, long instSize); 

TypeCodeNew(tk_struct, string name, string mbrname, 

TypeCode mbrTC, [...,] 

[mbrName and mbrTC repeat as needed] 

NULL); 

TypeCodeNew (tk union, string name, TypeCode swTC, 
longflag, long labelValue, string 
mbrName, TypeCode mbrTC,]...,] 

[flag, labelValue, mbrName and mbrTC repeat as needed] 

NULL); 

TypeCodeNew(tk_enum, string name, string enumld, [...,] 

[enumlds repeat as needed] 

NULL); 

TypeCodeNew(TCKindall OtherTAgValues); 

All TypeCodes created by TypeCodeNew should be destroyed (when no longer needed) using the TypeCode_free function. 




This function is a SOM-unique extension to the CORBA standard. 



TypeCodeNew - Related Information 



Functions 



• TypeCode_alignment 

• TypeCode_copy 

• TypeCode_equal 

• TypeCode_free 

• TypeCode_kind 

• TypeCode_param_count 

• TypeCode_parameter 

• TypeCode_print 

• TypeCode_size 

• TypeCode_setAlignment 



TypeCodeNew - Topics 



Select an item: 

Syntax 

Parameters 

Returns 

Remarks 

Related Information 
Glossary 



T ypeCode_param_cou nt 



TypeCode_param_count - Syntax 



This function obtains the number of parameters available in a given TypeCode. 



TypeCode tc; 

Environment *env; 

long rc; 

rc = TypeCode_param_count (tc, env) ; 



TypeCode_param_count Parameter - tc 



tc (TypeCode) 

The TypeCode whose parameter count is desired. 



TypeCode_param_count Parameter - env 



env (Environment *) 

A pointer to an Environment structure. The CORBA standard mandates the use of this structure as a standard way to return 
exception information when an error condition is detected. 



TypeCode_param_count Parameter - rc 



rc (long) 

Returns the actual number of parameters associated with the given TypeCode, in accordance with Table 1 . No exceptions are raised 
by this function. 



TypeCode_param_count - Parameters 



tc (TypeCode) 

The TypeCode whose parameter count is desired. 



env (Environment *) 

A pointer to an Environment structure. The CORBA standard mandates the use of this structure as a standard way to return 
exception information when an error condition is detected. 



rc (long) 

Returns the actual number of parameters associated with the given TypeCode, in accordance with Table 1 . No exceptions are raised 
by this function. 



TypeCode_param_count - Remarks 



The TypeCode_param_count function can be used to obtain the actual number of parameters contained in a specified TypeCode. Each 
TypeCode contains sufficient parameters to fully describe its underlying abstract data type. Refer to Table 1 . 



TypeCode_param_count - Related Information 



Functions 




• TypeCodeNew 

• TypeCode_alignment 

• TypeCode_equal 

• TypeCode_kind 

• TypeCode_parameter 

• TypeCode_copy 

• TypeCode_free 

• TypeCode_print 

• TypeCode_size 

• TypeCode_setAlignment 



TypeCode_param_count - Topics 



Select an item: 

Syntax 

Parameters 

Returns 

Remarks 

Related Information 
Glossary 



T ypeCode_parameter 



TypeCode_parameter - Syntax 



This function obtains a specified parameter from a given TypeCode. 



TypeCode 

Environment 

long 

any 



tc; 

*env; 

index; 

rc; 



rc = TypeCode_parameter (tc, env, index); 



TypeCode_parameter Parameter - tc 



tc (TypeCode) 

The TypeCode whose parameter is desired. 



TypeCode_parameter Parameter - env 



env (Environment *) 

A pointer to an Environment structure. The CORBA standard mandates the use of this structure as a standard way to return 
exception information when an error condition is detected. 



TypeCode_parameter Parameter - index 



index (long) 

The number of the desired parameter. Parameters are numbered from 0 to N-1, where N is the value returned by the 

Typecodeparamcount function. 



TypeCode_parameter Parameter - rc 



rc (any) 

Returns the requested parameter in the form of an any. This function raises the Bounds exception if the value of the index exceeds 
the number of parameters available in the given TypeCode. Because the values exist within the specified TypeCode, you should not 
free the results returned from this function. 

A bounds exception is also raised if this function is called on any of the IDL basic data types (see note above). 

An any is a basic IDL data type that is represented as the following structure in C or C++: 

typedef struct any { 

TypeCode „type; 
void * „value; 

} any; 



Since all TypeCode parameters have one of only three types (string, TypeCode, or long), the _type member will always be set to 
TC_string, TC_TypeCode, or TCJong, as appropriate. The _value member always points to the actual parameter datum. For 
example, the following code can be used to extract the name of a structure from a TypeCode of kind tk_struct in C: 

♦include <repostry.h> /* Interface Repository class */ 

♦include <typedef.h> /* Interface Repository TypeDef class */ 

♦include <somtcnst.h> /* TypeCode constants */ 

TypeCode x; 

Environment *ev = somGetGlobalEnvironment (); 

TypeDef aTypeDefObj; 
sequence (Contained) sc; 
any parm; 
string name; 

Repository repo; 



/* 1st, obtain a TypeCode from an Interface Repository object, 
* or use a TypeCode constant . 

*/ 



repo = RepositoryNew (); 
sc = _lookup_name (repo, ev, 

"AttributeDescription" , -1, "TypeDef", TRUE); 
if (sc._length) { 

aTypeDefObj = sc ._buf f er [ 0 ] ; 
x = get_type (aTypeDefObj, ev) ; 




else 



x = TC_AttributeDescription; 

if (TypeCode_kind (x, ev) == tk_struct) { 

parm = TypeCode_parameter (x, ev, 0) ; /* Get structure name */ 
if (TypeCode_kind (parm._type, ev) != tk_string) { 
printf ("Error, unexpected TypeCode : "); 

TypeCode_print (parm._type, ev) ; 

) else { 

name = *( (string *) parm._value) ; 
printf ("The struct name is %s\n", name) ; 

} 

} else { 

printf ("TypeCode is not a tk_struct: "); 

TypeCode_print (x, ev) ; 

} 



TypeCode_parameter - Parameters 



tc (TypeCode) 

The TypeCode whose parameter is desired, 
env (Environment *) 

A pointer to an Environment structure. The CORBA standard mandates the use of this structure as a standard way to return 
exception information when an error condition is detected. 

index (long) 

The number of the desired parameter. Parameters are numbered from 0 to N-1, where N is the value returned by the 

Typecode_param_count function. 

rc (any) 

Returns the requested parameter in the form of an any. This function raises the Bounds exception if the value of the index exceeds 
the number of parameters available in the given TypeCode. Because the values exist within the specified TypeCode, you should not 
free the results returned from this function. 

A bounds exception is also raised if this function is called on any of the IDL basic data types (see note above). 

An any is a basic IDL data type that is represented as the following structure in C or C++: 

typedef struct any { 

TypeCode _type; 
void * _value; 

} any; 



Since all TypeCode parameters have one of only three types (string, TypeCode, or long), the _type member will always be set to 
TC_string, TC_TypeCode, or TCJong, as appropriate. The _value member always points to the actual parameter datum. For 
example, the following code can be used to extract the name of a structure from a TypeCode of kind tk_struct in C: 

((include <repostry.h> /* Interface Repository class */ 

((include <typedef.h> /* Interface Repository TypeDef class */ 

((include <somtcnst.h> /* TypeCode constants */ 

TypeCode x; 

Environment *ev = somGetGlobalEnvironment (); 

TypeDef aTypeDef Ob j ; 
sequence (Contained) sc; 
any parm; 
string name; 

Repository repo; 



/* 1st, obtain a TypeCode from an Interface Repository object, 
* or use a TypeCode constant . 

*/ 




repo = RepositoryNew (); 
sc = _lookup_name (repo, ev, 

"AttributeDescription" , — 1, "TypeDef", TRUE); 
if (sc._length) { 

aTypeDefObj = sc ,_buf f er [ 0 ] ; 
x = get_type (aTypeDefObj, ev) ; 



else 

x = TC_AttributeDescription; 

if (TypeCode_kind (x, ev) == tk_struct) { 

parm = TypeCode_parameter (x, ev, 0) ; /* Get structure name */ 
if (TypeCode_kind (parm._type, ev) != tk_string) { 
printf ("Error, unexpected TypeCode : "); 

TypeCode_print (parm._type, ev) ; 

} else { 

name = *( (string *)parm,_value) ; 
printf ("The struct name is %s\n", name) ; 

} 

} else { 

printf ("TypeCode is not a tk_struct: "); 

TypeCode_print (x, ev) ; 

} 



TypeCode_parameter - Remarks 



The TypeCode_parameter function can be used to obtain any of the parameters contained in a given TypeCode. Refer to Table 1 for a list 
of the number and type of parameters associated with each category of TypeCode. 

Note: This function should not be used for any of the IDL basic data types (that is, any types in the TCKind enumeration that are not listed 
in table 1 under the TypeCode_Kind function). 



TypeCode_parameter - Related Information 



Functions 



• TypeCodeNew 

• TypeCode_alignment 

• TypeCode_equal 

• TypeCode_kind 

• TypeCode_param_count 

• TypeCode_copy 

• TypeCode_free 

• TypeCode_print 

• TypeCode_size 

• TypeCode_setAlignment 



TypeCode_parameter - Topics 



Select an item: 
Syntax 
Parameters 
Returns 



Remarks 

Related Information 
Glossary 



TypeCode_print 



TypeCode_print - Syntax 



This function writes all of the information contained in a given TypeCode to "stdout". 



TypeCode tc; 

Environment *env; 

TypeCode_print (tc, env) ; 



TypeCode_print Parameter - tc 



tc (TypeCode) 

The TypeCode to be examined. 



TypeCode_print Parameter - env 



env (Environment *) 

A pointer to an Environment structure. The CORBA standard mandates the use of this structure as a standard way to return 
exception information when an error condition is detected. 



TypeCode_print Parameter - rc 



TypeCode_print - Parameters 



tc (TypeCode) 

The TypeCode to be examined. 



env (Environment *) 

A pointer to an Environment structure. The CORBA standard mandates the use of this structure as a standard way to return 
exception information when an error condition is detected. 



rc 



TypeCode_print - Remarks 



The TypeCode_print function can be used during program debugging to inspect the contents of a TypeCode. It prints (in a human-readable 
format) all of the information contained in the TypeCode. The format of the information shown by TypeCode_print is the same form that 
could be used by a C programmer to code the corresponding TypeCodeNew function call to create the TypeCode. 

This function is a SOM-unique extension to the CORBA standard. 



TypeCode_print - Related Information 



Functions 



• TypeCodeNew 

• TypeCode_alignment 

• TypeCode_equal 

• TypeCode_kind 

• TypeCode_param_count 

• TypeCode_parameter 

• TypeCode_copy 

• TypeCode_free 

• TypeCode_size 

• TypeCode_setAlignment 



TypeCode_print - Topics 



Select an item: 

Syntax 

Parameters 

Returns 

Remarks 

Related Information 
Glossary 



TypeCode_setAlignment 



TypeCode_setAlignment - Syntax 



This function sets the alignment value for a given TypeCode. 



TypeCode tc; 

Environment *env; 

short alignment; 

TypeCode_setAlignment (tc, env, alignment); 



TypeCode_setAlignment Parameter - tc 



tc (TypeCode) 

The TypeCode to receive the new alignment value. 



TypeCode_setAlignment Parameter - env 



env (Environment *) 

A pointer to an Environment structure. 



TypeCode_setAlignment Parameter - alignment 



alignment (short) 

A short integer that specifies the alignment value. 



TypeCode_setAlignment Parameter - rc 



rc 



TypeCode_setAlignment - Parameters 



tc (TypeCode) 

The TypeCode to receive the new alignment value. 

env (Environment *) 

A pointer to an Environment structure. 

alignment (short) 

A short integer that specifies the alignment value. 



rc 



TypeCode_setAlignment - Related Information 



Functions 



• TypeCodeNew 

• TypeCode_alignment 

• TypeCode_equal 

• TypeCode_kind 

• TypeCode_param_count 

• TypeCode_parameter 

• TypeCode_size 

• TypeCode_free 

• TypeCode_print 



TypeCode_setAlignment - Topics 



Select an item: 
Syntax 
Parameters 
Returns 

Related Information 
Glossary 



TypeCode_size 



TypeCode_size - Syntax 



This function provides the size of an instance of the abstract data type described by a given TypeCode. 



TypeCode 

Environment 



tc; 

env; 



long 



rc; 



rc = TypeCode_size (tc, env); 



TypeCode_size Parameter - tc 



tc (TypeCode) 

The TypeCode whose instance size is desired. 



TypeCode_size Parameter - env 



env (Environment *) 

A pointer to an Environment structure. The CORBA standard mandates the use of this structure as a standard way to return 
exception information when an error condition is detected. 



TypeCode_size Parameter - rc 



rc (long) 

The amount of memory needed to hold an instance of the data type described by a given TypeCode. No exceptions are raised by 
this function. 



TypeCode_size - Parameters 



tc (TypeCode) 

The TypeCode whose instance size is desired. 



env (Environment *) 

A pointer to an Environment structure. The CORBA standard mandates the use of this structure as a standard way to return 
exception information when an error condition is detected. 



rc (long) 

The amount of memory needed to hold an instance of the data type described by a given TypeCode. No exceptions are raised by 
this function. 



TypeCode_size - Remarks 



The TypeCode_size function is used to obtain the size of an instance of the abstract data type described by a given TypeCode. 



This function is a SOM-unique extension to the CORBA standard. 



TypeCode_size - 


Related Information 


Funtions 

• TypeCodeNew 

• TypeCode_alignment 

• TypeCode_equal 

• TypeCode_kind 

• TypeCode_param_count 

• TypeCode_parameter 

• TypeCode_copy 

• TypeCode_free 

• TypeCode_print 

• TypeCode_setAlignment 





TypeCode_size - 


Topics 


Select an item: 
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Remarks 

Related Information 
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Metaclass Framework Reference 
SOMMBeforeAfter Metaclass 

File stem: sombacls 

Description 

SOMMBeforeAfteris a metaclass that defines two methods (sommBeforeMethod and sommAfterMethod) which are invoke before and 
after each invocation of every instance method. SOMMBeforeAfter is designed to be subclassed. Within the subclass, each of the two 
methods should be overridden with a method procedure appropriate to the particular application. The before and after methods are invoked 



on instances (ordinary objects) of a class whose metaclass is the subclass (or child) of SOMMBeforeAfter, whenever any method (inherited 
or introduced) of the class is invoked. 

Caution: The somDefaultlnit and somFree methods are among th methods that get before/after behavior. This implies that the following 
two obligations are imposed on the programmer of a SOMMBeforeAfter class. First, your implementation must guard against calling the 
sommBeforeMethod before somDefaultlnit has executed, when the object is not yet fully initialized. Second, the implementation must 
guard against calling sommAfterMethod after somFree at which time the object no longer exists. 

New methods 

None 

Overridden methods 
somDefaultlnit, somlnitMICIass 



sommAfterMethod 



sommAfterMethod - Syntax 



Specifies a method that is automatically called after execution of each client Method. 



SOMMBeforeAfter 

Environment 

SOMObject 

somld 

void 

va_list 



receiver; 

*env; 
object; 
methodld; 
*returnedvalue ; 
ap; 



sommAfterMethod (receiver , env, object, methodld, 
returnedvalue, ap) ; 



sommAfterMethod Parameter - receiver 



receiver (SOMMBeforeAfter) 

A pointer to an object (class) of metaclass SOMMBeforeAfter representing the class object that supports the method (such as, 
"myMethod") for which the "after" method will apply. 



sommAfterMethod Parameter - env 



env (Environment *) 

A pointer where the method can return exception information if an error is encountered. The dispatch method of SOMMBeforeAfter 
sets this parameter to NULL before dispatching the first sommBeforeMethod. 



sommAfterMethod Parameter - object 



object (SOMObject) 

A pointer to the instance of the receiver on which the method is invoked. 



sommAfterMethod Parameter - methodld 



methodld (somld) 

The SOM ID of the method (such as, "myMethod") that was invoked. 



sommAfterMethod Parameter - returnedvalue 



returnedvalue 

A pointer to the value returned by invoking the method ("myMethod") on an object. 



sommAfterMethod Parameter - ap 



ap (vajist) 

The list of input arguments to the method ("myMethod"). 



sommAfterMethod Parameter - rc 



sommAfterMethod - Parameters 



receiver (SOMMBeforeAfter) 

A pointer to an object (class) of metaclass SOMMBeforeAfter representing the class object that supports the method (such 
"myMethod") for which the "after" method will apply. 




env (Environment *) 

A pointer where the method can return exception information if an error is encountered. The dispatch method of SOMMBeforeAfter 
sets this parameter to NULL before dispatching the first sommBeforeMethod. 

object (SOMObject) 

A pointer to the instance of the receiver on which the method is invoked, 
methodld (somld) 

The SOM ID of the method (such as, "myMethod") that was invoked. 

returnedvalue 

A pointer to the value returned by invoking the method ("myMethod") on an object, 
ap (vajist) 

The list of input arguments to the method ("myMethod"). 



rc 



sommAfterMethod - Remarks 



The sommAfterMethod specifies a method that is automatically called after execution of each client method. The sommAfterMethod 
method is introduced in the SOMMBeforeAfter metaclass. The default implementation does nothing until it is overridden. The 
sommAfterMethod method is not called directly by the user. To define the desired "after" method, sommAfterMethod must be overridden 
in a metaclass that is a subclass (child) of the SOMMBeforeAfter metaclass. 

Caution: somFree is among the methods that get before/after behavior, which implies that the following obligation is imposed on the 
programmer of a sommAfterMethod. Specifically, care must be taken to guard against sommAfterMethod being called after somFree, at 
which time the object no longer exists. 



sommAfterMethod - Original Class 

SOMMBeforeAfter 



sommAfterMethod - Related Methods 

Methods 

• sommBeforeMethod 



sommAfterMethod - Topics 



Select an item: 

Syntax 

Parameters 

Returns 

Remarks 

Original Class 



Related Methods 
Glossary 



so m m Bef o re Meth od 



sommBeforeMethod - Syntax 



Specifies a method that is automatically called before execution of each client method. 



SOMMBef oreAfter 

Environment 

SOMObject 

somID 

va_list 

boolean 



receiver ; 
*env; 
object; 
methodid; 
ap; 
rc; 



rc 



sommBeforeMethod (receiver , env, 
methodid, ap) ; 



object, 



sommBeforeMethod Parameter - receiver 



receiver (SOMMBeforeAfter) 

A pointer to an object (class) of metaclass SOMMBeforeAfter representing the class object that supports the method (such as, 
"myMethod") for which the "before" method will apply. 



sommBeforeMethod Parameter - env 



env (Environment *) 

A pointer where the method can return exception information if an error is encountered. The dispatch method of SOMMBeforeAfter 
sets this parameter to NULL before dispatching the first sommBeforeMethod. 



sommBeforeMethod Parameter - object 



object (SOMObject) 

A pointer to the instance of the receiver on which the method is invoked. 



sommBeforeMethod Parameter - methodic! 



methodld (somID) 

The SOM Id of the method (such as, "myMethod") that was invoked. 



sommBeforeMethod Parameter - ap 



ap (vajist) 

The list of input arguments to the method ("myMethod''). 



sommBeforeMethod Parameter - rc 



rc (boolean) 

A boolean that indicates whether or not before/after dispatching should continue. If the value is TRUE, normal before/after 
dispatching continues. If the value is FALSE, the dispatching skips to the sommAfterMethod associated with the preceding 
sommBeforeMethod. This implies that the sommBeforeMethod must do any post-processing that might otherwise be done by the 
sommAfterMethod. Because before/after methods are paired within a SOMMBeforeAfter metaclass, this designe liminates the 
complexity of communicating to the sommAfterMethod that the sommBeforeMethod returned FALSE. 



sommBeforeMethod - Parameters 



receiver (SOMMBeforeAfter) 

A pointer to an object (class) of metaclass SOMMBeforeAfter representing the class object that supports the method (such as, 
"myMethod") for which the "before" method will apply. 

env (Environment *) 

A pointer where the method can return exception information if an error is encountered. The dispatch method of SOMMBeforeAfter 
sets this parameter to NULL before dispatching the first sommBeforeMethod. 

object (SOMObject) 

A pointer to the instance of the receiver on which the method is invoked, 
methodld (somID) 

The SOM Id of the method (such as, "myMethod") that was invoked, 
ap (vajist) 

The list of input arguments to the method ("myMethod''). 



rc (boolean) 

A boolean that indicates whether or not before/after dispatching should continue. If the value is TRUE, normal before/after 
dispatching continues. If the value is FALSE, the dispatching skips to the sommAfterMethod associated with the preceding 
sommBeforeMethod. This implies that the sommBeforeMethod must do any post-processing that might otherwise be done by the 
sommAfterMethod. Because before/after methods are paired within a SOMMBeforeAfter metaclass, this designe liminates the 
complexity of communicating to the sommAfterMethod that the sommBeforeMethod returned FALSE. 




sommBeforeMethod - Remarks 



The sommBeforeMethod specifies a method that is automatically called before execution of each client method. The sommBeforeMethod 
method is not called directly by the user. To define the desired "before” method, sommBeforeMethod must be overridden in a metaclass 
that is a subclass (child) of SOMMBeforeAfter. The default implementation does nothing until it is overridden. 

Caution: somDefaultlnit is among the methods that get before/after behavior, which implies that the following obligation is imposed on the 
programmer of a sommBeforeMethod. Specifically, care must be taken to guard against sommBeforeMethod being called before the 
somDefaultlnit method has executed and the object is not yet fully initialized. 



sommBeforeMethod ■ 


- Original Class 


SOMMBeforeAfter 





sommBeforeMethod ■ 


- Related Methods 


Methods 

• sommAfterMethod 





sommBeforeMethod ■ 


- Topics 
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SO M M S i ng I e I n stan ce 

File stem: snglicls 
Base 

SOMCIass 

Metaclass 



SOMCIass 



Ancestor Classes 
SOMCIass 

SOMObject 

Description 

SOMMSinglelnstance is a metaclass provided with the SOM Toolkit. It can be specified as the metaclass when defining a class for which 
only one instance can ever be created. The first call to < c/ass. A/ame>Hevj in C, the new operator in C++, or the somNew method creates 
the one possible instance of the class. Thereafter, any subsequent "new" calls return the first (and only) instance. SOMMSinglelnstance is 
thread safe. 

Alternatively, the /tfa'Ax’' sommGetSinglelnstance can be used to accomplish the same purpose. The method offers an advantage in that 
the call site explicitly shows that something special is occurring and that a new object is not necessarily being created. 

New methods 

The following list shows all the SOMMSinglelnstance methods. 

• sommGetSinglelnstance 

Overridden methods 

The following list shows all the methods overridden by the SOMMSinglelnstance class. These methods are overridden in order to modify the 
behavior defined by an ancestor class. 

■ somlnit 

• somNew 



sommGetSinglelnstance 



sommGetSinglelnstance - Syntax 



This method gets the one instance of a specified class for which only a single instance can exist. 



SOMMSinglelnstance receiver; 

Environment *env; 

SOMObject rc; 

rc = sommGetSinglelnstance (receiver, env) ; 



sommGetSinglelnstance Parameter - receiver 



receiver (SOMMSinglelnstance) 

A pointer to an object (class) whose metaclass is SOMMSinglelnstance (or is a subclass of it). 



sommGetSinglelnstance Parameter - env 



env (Environment *) 

A pointer where the method can return exception information if an error is encountered. 



sommGetSinglelnstance Parameter - rc 



rc (SOMObject) 

Returns a pointer to the single instance of the specified class. 



sommGetSinglelnstance - Parameters 



receiver (SOMMSinglelnstance) 

A pointer to an object (class) whose metaclass is SOMMSinglelnstance (or is a subclass of it), 
env (Environment *) 

A pointer where the method can return exception information if an error is encountered, 
rc (SOMObject) 

Returns a pointer to the single instance of the specified class. 



sommGetSinglelnstance - Remarks 



The sommGetSinglelnstance method gets a pointer to the one instance of a class for which only a single instance can exist. A class can 
have only a single instance when its metaclass is the SOMMSinglelnstance metaclass (or is a subclass of it). 

The first call to < c/ass A/ame>Ue\N in C, the new operator in C++, or the somNew method creates the one possible instance of the class. 
Thereafter, any subsequent "new" calls return the first (and only) instance. Using the sommGetSinglelnstance method, however, offers an 
advantage in that the call site explicitly shows that something special is occurring and that a new object is not necessarily being created. 
(That is, the sommGetSinglelnstance method creates the single instance if it does not already exist.) 



sommGetSinglelnstance - Original Class 



SOMMGetSinglelnstance 



sommGetSinglelnstance - Example Code 



xl = XXXNew ( ) ; 
x2 = XXXNew ( ) ; 




assert ( xl == x2 ) ; 

x3 = _sommGetSingleInstance ( _somGetClass ( xl ) , env ) ; 
assert ( x2 == x3 ) ; 



Note that the method sommGetSinglelnstance is invoked on the class object, because sommGetSinglelnstance is a method introduced 
by the metaclass SOMMSinglelnstance. 



sommGetSinglelnstance - Topics 



Select an item: 
Syntax 
Parameters 
Returns 
Remarks 
Original Class 
Example Code 
Glossary 



SOMMTraced Metaclass 



File stem: somtrcls 
Base 

Base Class 

Ancestor Classes 

SOMMBeforeAfter, SOMCIass, SOMObject 
Description 

New methods 

None 

Overridden methods 

somlnitMICIass, sommBeforeMethod, sommAfterMethod 



Event Management Framework Reference 



SOMEClientEvent 



File stem: clientev 



Base 



SOMEEvent 



Metaclass 

SOMCIass 

Ancestor Classes 
SOMEEvent 

SOMObject 

Description 

This class describes generic client events within the Event Manager. Client Events are defined, created, processed and destroyed entirely 
by the application. The application can queue several types of client events with EMan. When a client event occurs, EMan passes an 
instance of this class to the callback routine. The callback can query this object about its type and obtain any event-specific information. 

New methods 

The following list shows all the SOMEClientEvent methods. 

• somevGetEventClientData 

• somevGetEventClientType 

• somevSetEventClientData 

• somevSetEventClientType 

Overridden methods 

The following list shows all the methods overridden by the SOMEClientEvent class. These methods are overridden in order to modify the 
behavior defined by an ancestor class. 

• somlnit 



somevGetEventClientData 



somevGetEventClientData - Syntax 



This method returns the user-defined data associated with a client event. 



SOMEClientEvent receiver; 

Environment *env; 

void *rc; 

somevGetEventClientData (receiver, env, rc) ; 



somevGetEventClientData Parameter - receiver 



receiver (SOMEClientEvent) 

A pointer to an object of class SOMEClientEvent. 



somevGetEventClientData Parameter - env 



env (Environment *) 

A pointer to the Environment structure for the calling method. 



somevGetEventClientData Parameter - rc 



rc 

A pointer to user-defined client event data. 



somevGetEventClientData - Parameters 



receiver (SOMEClientEvent) 

A pointer to an object of class SOMEClientEvent. 

env (Environment *) 

A pointer to the Environment structure for the calling method. 

rc 

A pointer to user-defined client event data. 



somevGetEventClientData - Remarks 



This method returns the user-defined data (if any) associated with the Client Event object. This associated data for a given client event type 
is passed to EMan at the time of registration. 



somevGetEventClientData - Original Class 



SOMEClientEvent 



somevGetEventClientData - Related Methods 



Methods 



somevSetEventClientData 




somevGetEventClientData - Topics 



Select an item: 
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somevGetEventClientType 



somevGetEventClientType - Syntax 



This method returns the type name of a client event. 



SOMEClientEvent receiver; 

Environment *env; 

string rc; 

rc = somevGetEventClientType (receiver, env) ; 



somevGetEventClientType Parameter - receiver 



receiver (SOMEClientEvent) 

A pointer to an object of class SOMEClientEvent. 



somevGetEventClientType Parameter - env 



env (Environment *) 

A pointer to the Environment structure for the calling method. 



somevGetEventClientType Parameter - rc 



rc (string) 

A null terminated string identifying the client event type. 



somevGetEventClientType - Parameters 



receiver (SOMEClientEvent) 

A pointer to an object of class SOMEClientEvent. 

env (Environment *) 

A pointer to the Environment structure for the calling method, 
rc (string) 

A null terminated string identifying the client event type. 



somevGetEventClientType - Remarks 



This method returns the client event type of the Client Event object. Client event type is a string name assigned to the event by the 
application at the time of registering the event. 



somevGetEventClientType - Original Class 



SOMEClientEvent 



somevGetEventClientType - Related Methods 



Methods 



somevSetEventClientType 



somevGetEventClientType - Topics 
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somevSetEventClientData 



somevSetEventClientData - Syntax 



This method sets the user-defined data of a client event. 



SOMEClientEvent receiver; 

Environment *env; 

void *clientData; 

somevSetEventClientData (receiver, env, clientData) ; 



somevSetEventClientData Parameter - receiver 



receiver (SOMEClientEvent) 

A pointer to an object of class SOMEClientEvent. 



somevSetEventClientData Parameter - env 



env (Environment *) 

A pointer to the Environment structure for the calling method. 



somevSetEventClientData Parameter - clientData 



clientData 

A pointer to user-defined data for this client event. 



somevSetEventClientData Parameter - rc 



rc 



somevSetEventClientData - Parameters 



receiver (SOMEClientEvent) 

A pointer to an object of class SOMEClientEvent. 

env (Environment *) 

A pointer to the Environment structure for the calling method. 

clientData 

A pointer to user-defined data for this client event. 



rc 



somevSetEventClientData - Remarks 



This method sets the user-defined event data (if any) of the Client Event object. This associated data for a given client event type is passed 
to EMan at the time of registration. 



somevSetEventClientData - Original Class 



SOMEClientEvent 



somevSetEventClientData - Related Methods 



Methods 



somevGetEventClientData 



somevSetEventClientData - Topics 



Select an item: 




Syntax 

Parameters 

Returns 

Remarks 

Original Class 

Related Methods 

Glossary 



somevSetEventClientType 



somevSetEventClientType - Syntax 



This method sets the type name of a client event. 



SOMEClientEvent receiver; 

Environment *env; 

string clientType; 

somevSetEventClientType (receiver, env, clientType); 



somevSetEventClientType Parameter - receiver 



receiver (SOMEClientEvent) 

A pointer to an object of class SOMEClientEvent. 



somevSetEventClientType Parameter - env 



env (Environment *) 

A pointer to the Environment structure for the calling method. 



somevSetEventClientType Parameter - clientType 



clientType (string) 

A null terminated character string identifying the client event type. The contents of this string are entirely up to the user. However, 
while using class libraries that also use client events one must make sure that there are no name collisions. 



somevSetEventClientType Parameter - rc 



rc 



somevSetEventClientType - Parameters 



receiver (SOMEClientEvent) 

A pointer to an object of class SOMEClientEvent. 

env (Environment *) 

A pointer to the Environment structure for the calling method. 

clientType (string) 

A null terminated character string identifying the client event type. The contents of this string are entirely up to the user. However, 
while using class libraries that also use client events one must make sure that there are no name collisions. 

rc 



somevSetEventClientType - Remarks 



This method sets the client event type field of the Client Event object. Client event type is a string name assigned to the event by the 
application at the time of registering the event. 



somevSetEventClientType - Original Class 



SOMClientEvent 



somevSetEventClientType - Related Methods 



Methods 

• somevGetEventClientType 



somevSetEventClientType - Topics 




Select an item: 
Syntax 
Parameters 
Returns 
Remarks 
Original Class 
Related Methods 
Glossary 



SOMEEMan 



File stem: eman 
Base 

SOMObject 

Metaclass 

SOMMSinglelnstance 

Ancestor Classes 
SOMObject 

Description 

The Event Manager class (EMan for short) is used to handle several input events. The main purpose of this class is to provide a service that 
can do a blocked (or timed) wait on several event sources concurrently. Typically, in a main program, one registers an interest in an event 
type with EMan and specifies a callback (a procedure or a method) to be invoked when the event of interest occurs. After all the necessary 
registrations are complete, the main program ends with a call to someProcessEvents in EMan. This call is non-returning. Eman then waits 
on all registered event sources. The application is completely event driven at this point (that is, it does something only when an event 
occurs). The control returns to EMan after processing each event. Further registrations can be done from within the callback routines. 
Unregistrations can also be done from within the callback routines. 

For applications that want to have their own main loop, EMan provides a non-blocking call (the someProcessEvent method), which 
processes just one event (if any) and returns to the main loop immediately. Note that when this call is the only one in the application's main 
loop, CPU cycles are wasted in constantly polling for events. In this situation, the non-returning form of the someProcessEvents call is 
preferable. 

AIX Specifics : 

On AIX this event manager supports Timer, Sink (any file, pipe, socket, or Message Queue), Client and WorkProc events. 

OS/2 Specifics : 

On OS/2 this event manager supports Timer, Sink (sockets only), Client, and WorkProc events. 

Thread Safety: 

To cope with multi-threaded applications on OS/2, the event-manager methods are mutually exclusive (that is, at any time only one thread 
can be executing inside of EMan). If an application thread needs to stop EMan from running (that is, to achieve mutual exclusion with 
EMan), it can use the two methods someGetEmanSem and someReleaseEManSem to acquire and release EMan semaphore(s). On AIX, 
since AIX does not support threads (at present), calling these two methods has no effect. 

New methods 

The following list shows all the SOMEEMan methods. 

■ someGetEmanSem 

• someReleaseEManSem 

• someChangeRegData 

• someProcessEvent 

■ someProcessEvents 

• someQueueEvent 

• someRegister 

• someRegisterEv 



• someRegisterProc 

■ someShutdown 

• someUnegister 

Overridden methods 

The following list shows all the methods overridden by the SOMEEMan class. These methods are overridden in order to modify the behavior 
defined by an ancestor class. 

■ somlnit 

• somUninit 



someChangeRegData 



someChangeRegData - Syntax 



This method changes the registration data associated with a specified registration ID. 



SOMEEMan 

Environment 

long 

SOMEEMRegisterData 



receiver; 

*env; 

registrationld; 

registerData; 



someChangeRegData (receiver, env, registrationld, 
registerData) ; 



someChangeRegData Parameter - receiver 



receiver (SOMEEMan) 

A pointer to an object of class SOMEEMan. 



someChangeRegData Parameter - env 



env (Environment *) 

A pointer to the Environment structure for the calling method. 



someChangeRegData Parameter - registrationld 



registrationld (long) 

The registration ID of the event interest whose data is being changed. 



someChangeRegData Parameter - registerData 



registerData (SOMEEMRegisterData) 

A pointer to the registration data object whose contents will replace the existing registration information with EMan. 



someChangeRegData Parameter - rc 



someChangeRegData - Parameters 



receiver (SOMEEMan) 

A pointer to an object of class SOMEEMan. 

env (Environment *) 

A pointer to the Environment structure for the calling method. 

registrationld (long) 

The registration ID of the event interest whose data is being changed. 
registerData (SOMEEMRegisterData) 

A pointer to the registration data object whose contents will replace the existing registration information with EMan. 



rc 



someChangeRegData - Remarks 



This method is called to change the registration data associated with an existing registration of EMan. The existing registration is identified 
by the reg/stration/d parameter. This ID must be the one returned by EMan when the event interest was originally registered with EMan. 
Further, the registration must be active (that is, it must not have been unregistered). The result of providing a non-existent or invalid 
registration ID is a "no op". 



someChangeRegData - Original Class 




SOMEEMan 



someChangeRegData - Related Methods 



Methods 



someRegister 

SomeRegisterEv 

SomeRegisterProc 



someChangeRegData - Example Code 



#include <eman.h> 
SOMEEMan *EManPtr; 
SOMEEMRegisterData *data; 
Environment *Ev; 
long Regld; 



someChangeRegData (EManPtr, Ev, Regld, data); 



someChangeRegData - Topics 



Select an item: 
Syntax 
Parameters 
Returns 
Remarks 
Original Class 
Example Code 
Related Methods 
Glossary 



someGetEManSem 



someGetEManSem - Syntax 



This method acquires EMan semaphore(s) to achieve mutual exclusion with EMan's activity. 



SOMEEMan receiver; 

Environment *env; 

someGetEManSem (receiver, env) ; 



someGetEManSem Parameter - receiver 



receiver (SOMEEMan) 

A pointer to an object of class SOMEEMan. 



someGetEManSem Parameter - env 



env (Environment *) 

A pointer to the Environment structure for the calling method. 



someGetEManSem Parameter - rc 



someGetEManSem - Parameters 



receiver (SOMEEMan) 

A pointer to an object of class SOMEEMan. 

env (Environment *) 

A pointer to the Environment structure for the calling method. 



rc 



someGetEManSem - Remarks 



When EMan is used on OS/2, multiple threads can invoke methods on EMan concurrently. EMan protects its internal data by acquiring SOM 



toolkit semaphore(s). The same semaphore(s) are made available to users of EMan through the methods someGetEManSem and 
someReleaseEManSem. If an application desires to prevent EMan event processing from interfering with its own activity (in another thread, 
of course), then it can call the someGetEManSem method and acquire EMan semaphore(s). EMan activity will resume when the application 
thread releases the same semaphore(s) by calling someReleaseEManSem. 

Callers should not hold this semaphore for too long, since it essentially stops EMan activity for that duration and may cause EMan to miss 
some important event processing. The maximum duration for which one can hold this semaphore depends on how frequently EMan must 
process events. 

On AIX, calling this method has no effect. 



someGetEManSem - Original Class 



SOMEEMan 



someGetEManSem - Related Methods 



Methods 

■ someReleaseEManSem 



someGetEManSem - Example Code 



#include <eman.h> 
SOMEEMan *EManPtr; 
Environment *Ev; 



someGetEManSem (EManPtr, Ev) ; 

/* Do the work that needs mutual exclusion with EMan */ 

someReleaseEManSem (EManPtr, Ev) ; 



someGetEManSem - Topics 



Select an item: 
Syntax 
Parameters 
Returns 
Remarks 
Original Class 
Example Code 
Related Methods 
Glossary 



someProcessEvent 



someProcessEvent - Syntax 



This method processes one event. 



SOMEEMan receiver; 

Environment *env; 

unsigned long mask; 

someProcessEvent (receiver, env, mask) ; 



someProcessEvent Parameter - receiver 



receiver (SOMEEMan) 

A pointer to an object of class SOMEEMan. 



someProcessEvent Parameter - env 



env (Environment *) 

A pointer to the Environment structure for the calling method. 



someProcessEvent Parameter - mask 



mask (unsigned long) 

A bit mask indicating the types of events to look for and process. 



someProcessEvent Parameter - rc 



rc 



someProcessEvent - Parameters 



receiver (SOMEEMan) 

A pointer to an object of class SOMEEMan. 

env (Environment *) 

A pointer to the Environment structure for the calling method, 
mask (unsigned long) 

A bit mask indicating the types of events to look for and process. 



rc 



someProcessEvent - Remarks 



Processes one event. This call is non-blocking. If there are no events to process it returns immediately. The mask specifies which events to 
process. The mask is formed by OR'ing the bit constants specified in "eventmsk.h". 



someProcessEvent - Original Class 



SOMEEMan 



someProcessEvent - Related Methods 



Methods 

• someProcessEvents 

• someRegister 

• someRegisterProc 

• someRegisterEv 



someProcessEvent - Example Code 



#include <eman.h> 

main ( ) 

{ 

Environment *testEnv = somGetGlobalEnvironment ( ) ; 




SOMEEMan *some_gEMan = SOMEEManNew ( ) ; 

/* Do some registrations */ 

while (1) { 

_someProcessEvent (some_gEMan, testEnv, 

EMProcessTimerEvent 
EMProcessSinkEvent 
EMProcessClientEvent ) ; 

/*** Do other main loop work, if needed. ***/ 



} /* end of main */ 



someProcessEvent - Topics 



Select an item: 
Syntax 
Parameters 
Returns 
Remarks 
Original Class 
Example Code 
Related Methods 
Glossary 



someProcessEvents 



someProcessEvents - Syntax 



This method processes infinite events. 

SOMEEMan receiver; 

Environment *env; 

someProcessEvents (receiver, env) ; 



someProcessEvents Parameter - receiver 



receiver (SOMEEMan) 

A pointer to an object of class SOMEEMan. 



someProcessEvents Parameter - env 



env (Environment *) 

A pointer to the Environment structure for the calling method. 



someProcessEvents Parameter - rc 



rc 



someProcessEvents - Parameters 



receiver (SOMEEMan) 

A pointer to an object of class SOMEEMan. 

env (Environment *) 

A pointer to the Environment structure for the calling method. 

rc 



someProcessEvents - Remarks 



This call loops forever waiting for events and dispatching them. The only way this can be broken is by calling someShutdown in a callback 
routine. It is a programming error to call this method without having registered interest in any events with EMan. Typically, a call to this 
method is the last statement in an application's main program. 



someProcessEvents - Original Class 

SOMEEMan 



someProcessEvents - Related Methods 



Methods 



someProcessEvent 

someRegister 

someRegisterProc 

someRegisterEv 




someProcessEvents - Example Code 



#include <eman.h> 

main ( ) 

{ 

Environment *testEnv = somGetGlobalEnvironment ( ) ; 
SOMEEMan *some_gEMan = SOMEEManNew ( ) ; 

/* Do some registrations */ 

_someProcessEvents (some_gEMan, testEnv) ; 

} /* end of main */ 



someProcessEvents - Topics 



Select an item: 
Syntax 
Parameters 
Returns 
Remarks 
Original Class 
Example Code 
Related Methods 
Glossary 



someQueueEvent 



someQueueEvent - Syntax 



This method enqueues the specified client event. 



SOMEEMan receiver; 

Environment *env; 

SOMEClientEvent event; 

someQueueEvent (receiver, env, event) ; 



someQueueEvent Parameter - receiver 



receiver (SOMEEMan) 

A pointer to an object of class SOMEEMan. 



someQueueEvent Parameter - env 



env (Environment *) 

A pointer to the Environment structure for the calling method. 



someQueueEvent Parameter - event 

event (SOMEClientEvent) 



someQueueEvent Parameter - rc 



someQueueEvent - Parameters 



receiver (SOMEEMan) 

A pointer to an object of class SOMEEMan. 

env (Environment *) 

A pointer to the Environment structure for the calling method, 
event (SOMEClientEvent) 



someQueueEvent - Remarks 



Client events are defined, created, processed and destroyed by the application. EMan simply provides a means to enqueue and dequeue 




client events. Client events can be used in several ways. For example, if an application component wants to handle an input message 
arriving on a socket at a later time than when it arrives, it can receive the message in the socket callback routine, create a client event out of 
it, and queue it with EMan. EMan can be asked for the client event at a later time when the application is ready to handle it. Client events 
can also be useful to hide the origin of event sources (that is, the original event handlers receive the events and create client events in their 
place). 

Dequeue is not a user-visible operation. Once a client event is queued, only EMan can dequeue it. 



someQueueEvent - Original Class 

SOMEEMan 



someQueueEvent - Example Code 



#include <eman.h> 

SOMEClientEvent *clientEventl ; 

clientEventl = SOMEClientEventNew ( ) ; 

/* create a client event of type "ClientTypel" */ 

_somevSetEventClientType ( clientEventl, testEnv, "ClientTypel" ); 
_somevSetEventClientData ( clientEventl, testEnv, "Test Msg"); 



/* whenever it is desired to cause this client event to happen, 
call someQueueEvent Method with this clientEvent */ 
_someQueueEvent (some_gEMan, env, clientEventl); 



someQueueEvent - Topics 



Select an item: 
Syntax 
Parameters 
Returns 
Remarks 
Original Class 
Example Code 
Glossary 



someRegister 



someRegister - Syntax 



This method registers an object/method pair with EMan, given a specified reg/sterData object. 



SOMEEMan 

Environment 

SOMEEMRegisterData 

SOMObject 

string 

void 

long 



receiver; 

*env; 

registerData; 
targetOb ject ; 
targetMethod; 
*targetData; 
rc; 



rc = someRegister (receiver , env, registerData, 
targetOb ject , targetMethod, targetData) ; 



someRegister Parameter - receiver 



receiver (SOMEEMan) 

A pointer to an object of class SOMEEMan. 



someRegister Parameter - env 



env (Environment *) 

A pointer to the Environment structure for the calling method. 



someRegister Parameter - registerData 



registerData (SOMEEMRegisterData) 

A pointer to the registration data object that contains all the necessary information about the event for which an interest is being 
registered with EMan. 



someRegister Parameter - targetObject 



targetObject (SOMObject) 

A pointer to the object that is the target of the callback method. 



someRegister Parameter - targetMethod 



targetMethod (string) 

The name of the callback method. 



someRegister Parameter - targetData 



targetData 

A pointer to a data structure to be passed to the callback method when the event occurs. 



someRegister Parameter - rc 

rc (long) 

The registration ID. 



someRegister - Parameters 



receiver (SOMEEMan) 

A pointer to an object of class SOMEEMan. 

env (Environment *) 

A pointer to the Environment structure for the calling method. 
registerData (SOMEEMRegisterData) 

A pointer to the registration data object that contains all the necessary information about the event for which an interest is being 
registered with EMan. 

targetObject (SOMObject) 

A pointer to the object that is the target of the callback method. 

targetMethod (string) 

The name of the callback method. 

targetData 

A pointer to a data structure to be passed to the callback method when the event occurs, 
rc (long) 

The registration ID. 



someRegister - Remarks 



This method allows for registering an event of interest with EMan, with an object method as the callback. It is assumed that the target 
method has been declared as using OIDL callstyle. The event of interest and its details are filled in a registration data object reg/sterData . 
The information about the callback routine is indicated by targetObject and targetMetboct . 




A mismatch between the target method's callstyle and the registration method used (that is, someRegister vs. someRegisterEv) can result 
in unpredictable results. Also see the callstyle modifier of the SOM Interface Definition Language described in Chapter 4 "SOM IDL and the 
SOM Compiler” of the SOM Too/k/t User's Gu/de. 

Note: The target method is called using name-lookup method resolution. 



someRegister - Original Class 



SOMEEMan 



someRegister - Related Methods 



Methods 

■ someRegisterEv 

• someRegisterProc 

• someUnRegister 



someRegister - Example Code 



#include <eman.h> 

#include <emobj.h> 

Environment *testEnv = somGetGlobalEnvironment ( ) ; 
some_gEMan = SOMEEManNew ( ) ; /* create an EMan object */ 

data = SOMEEMRegisterDataNew ( ); /* create a reg data object */ 
target = EMOb jectNew ( ) ; /* create a target object */ 

/* reRegister a timer event */ 

_someClearRegData ( data, env ); 

_someSetRegDataEventMask ( data, env, EMTimerEvent , NULL ); 
_someSetRegDataTimerInterval ( data, env, 100 ) ; 
regldl = ^someRegister ( some_gEMan, env, data, target, 

"eventMethod" , "Timer 100" ); 



someRegister - Topics 



Select an item: 
Syntax 
Parameters 
Returns 
Remarks 
Original Class 
Example Code 
Related Methods 
Glossary 



someRegisterEv 



someRegisterEv - Syntax 



This method registers the (object, method, Environment parameter) combination of a callback with EMan, given a specified registerData 
object. 



SOMEEMan 

Environment 

SOMEEMRegisterData 

SOMObject 

Environment 

string 

void 

long 



receiver; 

*env; 

registerData; 
targetOb ject ; 
callbackEv; 
targetMethod; 
*targetData; 
rc; 



rc = someRegisterEv (receiver, env, registerData, 
targetOb ject , callbackEv, targetMethod, 
targetData) ; 



someRegisterEv Parameter - receiver 



receiver (SOMEEMan) 

A pointer to an object of class SOMEEMan. 



someRegisterEv Parameter - env 



env (Environment *) 

A pointer to the Environment structure for the calling method. 



someRegisterEv Parameter - registerData 



registerData (SOMEEMRegisterData) 

A pointer to registration data object that contains all the necessary information about the event for which an interest is being 
registered with EMan. 



someRegisterEv Parameter - targetObject 



targetObject (SOMObject) 

A pointer to the object which is the target of the callback method 



someRegisterEv Parameter - callbackEv 



callbackEv (Environment) 

A pointer to the Environment structure to be passed to the callback method 



someRegisterEv Parameter - targetMethod 



targetMethod (string) 

The name of the callback method. 



someRegisterEv Parameter - targetData 



targetData 

A pointer to a data structure to be passed to the callback method when the event occurs. 



someRegisterEv Parameter - rc 



rc (long) 

The registration ID. 



someRegisterEv - Parameters 



receiver (SOMEEMan) 




A pointer to an object of class SOMEEMan. 



env (Environment *) 

A pointer to the Environment structure for the calling method. 
registerData (SOMEEMRegisterData) 

A pointer to registration data object that contains all the necessary information about the event for which an interest is being 
registered with EMan. 

targetObject (SOMObject) 

A pointer to the object which is the target of the callback method 
callbackEv (Environment) 

A pointer to the Environment structure to be passed to the callback method 

targetMethod (string) 

The name of the callback method. 

targetData 

A pointer to a data structure to be passed to the callback method when the event occurs, 
rc (long) 

The registration ID. 



someRegisterEv - Remarks 



This method allows for registering an event interest with EMan with an object method as callback. The ca/tbackEv is used as the 
environment pointer when EMan makes the callback. It is assumed that the target method has been declared as using IDL callstyle. The 
event of interest and its details are filled in a registration data object reg/sterData . The information about the callback routine is indicated by 
targetObject and targetMethod . 

A mismatch in the target method's callstyle and the registration method called (someRegister vs. someRegisterEv) can result in 
unpredictable results. Also see the callstyle modifier of the SOM Interface Definition Language described in Chapter 4 "SOM IDL and the 
SOM Compiler" of the SOM Too/k/t User's Guide. 

Note: The target method is called using name-lookup method resolution. 



someRegisterEv - Original Class 



SOMEEMan 



someRegisterEv - Related Methods 



Methods 

• someRegister 

• someRegisterProc 

• somellnRegister 



someRegisterEv - Example Code 




#include <eman.h> 

#include <emobj.h> 

Environment *testEnv = somGetGlobalEnvironment ( ) ; 

Environment *targetEv = somGetGlobalEnvironment () ; 
some_gEMan = SOMEEManNew ( ) ; /* create an EMan object */ 

data = SOMEEMRegisterDataNew ( ); /* create a reg data object */ 
target = EMOb jectNew ( ) ; /* create a target object */ 

/* reRegister a timer event */ 

_someClearRegData ( data, env ); 

_someSetRegDataEventMask ( data, env, EMTimerEvent , NULL ); 
_someSetRegDataTimerInterval ( data, env, 100 ) ; 

regldl = _someRegisterEv ( some_gEMan, env, data, target , targetEv, 

"eventMethod" , "Timer 100" ); 

/* eventMethod of target is assumed to use callstyle=idl */ 



someRegisterEv - Topics 



Select an item: 
Syntax 
Parameters 
Returns 
Remarks 
Original Class 
Example Code 
Related Methods 
Glossary 



someRegisterProc 



someRegisterProc - Syntax 



This method registers the procedure with EMan given the specified registerData . 



SOMEEMan 

Environment 

SOMEEMRegisterData 

EMRegProc 

void 

long 



receiver; 

*env; 

registerData; 

*targetProcedure; 

*targetData; 

rc; 



rc = someRegisterProc (receiver, env, registerData, 
targetProcedure, targetData) ; 



someRegisterProc Parameter - receiver 



receiver (SOMEEMan) 

A pointer to an object of class SOMEEMan. 



someRegisterProc Parameter - env 



env (Environment *) 

A pointer to the Environment structure for the calling method. 



someRegisterProc Parameter - registerData 



registerData (SOMEEMRegisterData) 

A pointer to registration data object that contains all the necessary information about the event for which an interest is being 
registered with EMan. 



someRegisterProc Parameter - targetProcedure 



targetProcedure (EMRegProc *) 

A pointer to the procedure (callback) that is called when the registered event occurs. 



someRegisterProc Parameter - targetData 



targetData 



someRegisterProc Parameter - rc 



rc (long) 

The registration ID. 




someRegisterProc - Parameters 



receiver (SOMEEMan) 

A pointer to an object of class SOMEEMan. 

env (Environment *) 

A pointer to the Environment structure for the calling method. 
registerData (SOMEEMRegisterData) 

A pointer to registration data object that contains all the necessary information about the event for which an interest is being 
registered with EMan. 

targetProcedure (EMRegProc *) 

A pointer to the procedure (callback) that is called when the registered event occurs. 

targetData 



rc (long) 

The registration ID. 



someRegisterProc - Original Class 

SOMEEMan 



someRegisterProc - Related Methods 



Methods 



someRegister 

someRegisterEv 

someUnRegister 



someRegisterProc - Example Code 



#include <eman.h> 

void MyCallBack (SOMEEvent *event, void *somedata) { 



Environment *testEnv = somGetGlobalEnvironment ( ) ; 

some_gEMan = SOMEEManNew ( ) ; /* create an EMan object */ 

data = SOMEEMRegisterDataNew ( ); /* create a reg data object */ 

/* reRegister a timer event */ 

_someClearRegData ( data, env ); 




_someSetRegDataEventMask ( data, env, EMTimerEvent , NULL ); 
_someSetRegDataTimerInterval ( data, env, 100 ) ; 
regldl = _someRegisterProc ( some_gEMan, env, data, 

MyCallBack, "Timer 100" ); 



someRegisterProc - Topics 



Select an item: 
Syntax 
Parameters 
Returns 
Original Class 
Example Code 
Related Methods 
Glossary 



someReleaseEManSem 



someReleaseEManSem - Syntax 



This method releases the semaphore obtained by the someGetEManSem method. 

SOMEEMan receiver; 

Environment *env; 

someReleaseEManSem (receiver, env) ; 



someReleaseEManSem Parameter - receiver 



receiver (SOMEEMan) 

A pointer to an object of class SOMEEMan. 



someReleaseEManSem Parameter - env 



env (Environment *) 

A pointer to the Environment structure for the calling method. 



someReleaseEManSem Parameter 



rc 



rc 



someReleaseEManSem - Parameters 



receiver (SOMEEMan) 

A pointer to an object of class SOMEEMan. 

env (Environment *) 

A pointer to the Environment structure for the calling method. 



rc 



someReleaseEManSem - Remarks 



When EMan is used on OS/2, multiple threads can invoke methods on EMan concurrently. EMan protects its internal data by acquiring SOM 
toolkit semaphore(s). The same semaphore(s) are made available to users of EMan through the methods someGetEManSem and 
someReleaseEManSem. If an application desires to prevent EMan's event processing from interfering with its own activity (in another 
thread, of course), then it can call the someGetEManSem method and acquire EMan semaphore(s). EMan activity will resume when the 
application thread releases the same semaphore(s) by calling someReleaseEManSem. 

Callers should not hold this semaphore for too long, since it essentially stops EMan activity for that duration and may cause EMan to miss 
some important event processing. The maximum duration for which one can hold this semaphore depends on how frequently EMan must 
process events. 

On AIX, calling this method has no effect. 



someReleaseEManSem - Original Class 

SOMEEMan 



someReleaseEManSem - Related Methods 



Methods 



someGetEManSem 




someReleaseEManSem - Example Code 



#include <eman.h> 
SOMEEMan * EManPtr; 
Environment *Ev; 



someGetEManSem (EManPtr , Ev) ; 

/* Do the work that needs mutual exclusion with EMan */ 

someReleaseEManSem (EManPtr , Ev) ; 



someReleaseEManSem - Topics 



Select an item: 
Syntax 
Parameters 
Returns 
Remarks 
Original Class 
Example Code 
Related Methods 
Glossary 



someShutdown 



someShutdown - Syntax 



This method shuts down an EMan event loop. (That is, this makes the someProcessEvents return!) 

SOMEEMan receiver; 

Environment *env; 

someShutdown (receiver, env) ; 



someShutdown Parameter - receiver 



receiver (SOMEEMan) 

A pointer to an object of class SOMEEMan. 



someShutdown Parameter - env 



env (Environment *) 

A pointer to the Environment structure for the calling method. 



someShutdown Parameter - rc 



rc 



someShutdown - Parameters 



receiver (SOMEEMan) 

A pointer to an object of class SOMEEMan. 

env (Environment *) 

A pointer to the Environment structure for the calling method. 



rc 



someShutdown - Remarks 



This can be called from a callback routine to break the someProcessEvents loop. 



someShutdown - Original Class 

SOMEEMan 



someShutdown - Related Methods 




Methods 



someProcessEvents 



someShutdown - Example Code 



#include <eman.h> 

SOMEEMan *some_gEMan; 

void MyCallBack (SOMEEvent *event, void *somedata) { 

_someShutdown ( some_gEMan, env) ; 

} 

main ( ) 

{ 

Environment *testEnv = somGetGlobalEnvironment ( ) ; 

SOMEEMan *some_gEMan = SOMEEManNew ( ) ; 

/* Do some registrations. At least one involving MyCallBack */ 

_someProcessEvents (some_gEMan, testEnv) ; 

} 



someShutdown - Topics 



Select an item: 
Syntax 
Parameters 
Returns 
Remarks 
Original Class 
Example Code 
Related Methods 
Glossary 



someUnRegister 



somellnRegister - Syntax 



This method unregisters the event interest associated with a specified reg/strat/on/d within EMan. 



SOMEEMan 



receiver; 



Environment 

long 



env; 

registrationld; 



someUnRegister (receiver, env, registrationld); 



someUnRegister Parameter - receiver 



receiver (SOMEEMan) 

A pointer to an object of class SOMEEMan. 



someUnRegister Parameter - env 



env (Environment *) 

A pointer to the Environment structure for the calling method. 



someUnRegister Parameter - registrationld 



registrationld (long) 

The registration ID of the event that needs to be unregistered. 



someUnRegister Parameter - rc 



rc 



someUnRegister - Parameters 



receiver (SOMEEMan) 

A pointer to an object of class SOMEEMan. 

env (Environment *) 

A pointer to the Environment structure for the calling method. 

registrationld (long) 

The registration ID of the event that needs to be unregistered. 



rc 



someUnRegister - Remarks 



When an application is no longer interested in a given event, it can unregister the event interest from EMan. EMan will stop making 
callbacks on this event, even if the event source continues to be active and generates events. 



someUnRegister - Original Class 

SOMEEMan 



someUnRegister - Related Methods 



Methods 



someRegister 

someRegisterEv 

someRegisterProc 



someUnRegister - Example Code 



#include <eman.h> 
long regldl; 



/* Register a timer */ 

regldl = _someRegisterEv ( some_gEMan,env, data, target , targetEv, 

"eventMethod" , "Timer 100" ); 



/* Unregister the timer */ 
_someUnRegister ( some_gEMan, env, regldl); 



someUnRegister - Topics 



Select an item: 
Syntax 
Parameters 
Returns 



Remarks 
Original Class 
Example Code 
Related Methods 
Glossary 



SOMEEMRegisterData 



File stem: emregdat 
Base 

SOMObject 

Metaclass 

SOMCIass 

Ancestor Classes 
SOMCIass 

WPObject 

Description 

This class is used for holding registration information for event types to be registered with EMan. EMan extracts all needed information from 
this object and saves the information in its internal data structures. An instance of this class must be created, properly initialized, and passed 
to the registration methods of EMan for registering interest in any kind of event. 

New methods 

The following list shows all the SOMEEMRegisterData methods. 

• someClearRegData 

• someSetRegDataClientType 

• someSetRegDataEventMask 

• someSetRegDataSink 

• someSetRegDataSinkMask 

• someSetRegDataTimerCount 

• someSetRegDataTimerlnterval 

Overridden methods 

The following list shows all the methods overridden by the SOMEEMRegisterData class. These methods are overridden in order to modify 
the behavior defined by an ancestor class. 

• somlnit 

■ somUnlnit 



someClearRegData 



someClearRegData - Syntax 



This method clears the registration data. 

This method initializes all fields of a RegData object to their default values. 

SOMEEMRegisterData receiver; 

Environment *env; 

someClearRegData (receiver , env) ; 



someClearRegData Parameter - receiver 



receiver (SOMEEMRegisterData) 

A pointer to an object of class SOMEEMRegisterData. 



someClearRegData Parameter - env 



env (Environment *) 

A pointer to the Environment structure for the calling method. 



someClearRegData Parameter - rc 



rc 



someClearRegData - Parameters 



receiver (SOMEEMRegisterData) 

A pointer to an object of class SOMEEMRegisterData. 

env (Environment *) 

A pointer to the Environment structure for the calling method. 



rc 



someClearRegData - Original Class 



SOMEEMRegisterData 



someClearRegData - Topics 



Select an item: 

Syntax 

Parameters 

Returns 

Original Class 

Glossary 



someSetRegDataClientType 



someSetRegDataClientType - Syntax 



This method sets the type name for a client event. 



SOMEEMRegisterData receiver; 

Environment *env; 

string clientType; 

someSetRegDataClientType (receiver , env, clientType); 



someSetRegDataClientType Parameter - receiver 



receiver (SOMEEMRegisterData) 

A pointer to an object of class SOMEEMRegisterData. 



someSetRegDataClientType Parameter - env 



env (Environment *) 

A pointer to the Environment structure for the calling method. 



someSetRegDataClientType Parameter - clientType 



clientType (string) 

A null-terminated character string identifying the client event type. The contents of this string are entirely up to the user. However, 
while using class libraries that also use client events, one must make sure that there are no name collisions. 



someSetRegDataClientType Parameter - rc 



rc 



someSetRegDataClientType - Parameters 



receiver (SOMEEMRegisterData) 

A pointer to an object of class SOMEEMRegisterData. 

env (Environment *) 

A pointer to the Environment structure for the calling method. 

clientType (string) 

A null-terminated character string identifying the client event type. The contents of this string are entirely up to the user. However, 
while using class libraries that also use client events, one must make sure that there are no name collisions. 



rc 



someSetRegDataClientType - Remarks 



Client events are defined, created, processed, and destroyed entirely by the application. The application can queue several types of client 
events with EMan. This method sets the client event type field of the registration data object. Thus, this information is communicated to 
EMan, helping it deal with enqueueing and dequeing the different client events. 



someSetRegDataClientType - Original Class 

SOMEEMRegisterData 



someSetRegDataClientType - Related Methods 




Methods: 



someClearRegData 



someSetRegDataClientType - Topics 



Select an item: 
Syntax 
Parameters 
Returns 
Remarks 
Original Class 
Related Methods 
Glossary 



someSetRegDataEventMask 



someSetRegDataEventMask - Syntax 



This method sets the generic event mask within the registration data using NULL terminated event type list. 



SOMEEMRegisterData receiver; 

Environment *env; 

long eventType; 

va_list ap; 

someSetRegDataEventMask (receiver , env, eventType, 
ap) ; 



someSetRegDataEventMask Parameter - receiver 



receiver (SOMEEMRegisterData) 

A pointer to an object of class SOMEEMRegisterData. 



someSetRegDataEventMask Parameter - env 



env (Environment *) 

A pointer to the Environment structure for the calling method. 



someSetRegDataEventMask Parameter - eventType 



eventType (long) 

A bit constant indicating the type of event being registered with EMan. 



someSetRegDataEventMask Parameter - ap 



ap (vajist) 

Additional event types (usually NULL). 



someSetRegDataEventMask Parameter - rc 



rc 



someSetRegDataEventMask - Parameters 



receiver (SOMEEMRegisterData) 

A pointer to an object of class SOMEEMRegisterData. 

env (Environment *) 

A pointer to the Environment structure for the calling method. 

eventType (long) 

A bit constant indicating the type of event being registered with EMan. 
ap (vajist) 

Additional event types (usually NULL). 

rc 



someSetRegDataEventMask - Remarks 




This allows setting the event mask within the registration data object. Essentially, this tells EMan what kind of event is being registered with 
it. The event type list is a series of constants defined in eventmsk.h. Although the current interface supports a NULL terminated list of event 
types, currently each registration with EMan names only one event type. Thus, one usually gives only one named constant as the event type 
and follows it with a NULL parameter. 



someSetRegDataEventMask - Original Class 



SOMEEMRegisterData 



someSetRegDataEventMask - Related Methods 



Methods: 



someSetRegDataSink 

someClearRegData 



someSetRegDataEventMask - Example Code 



#include <eman.h> 
long regldl; 
int msgsock; 



/* Register msgsock socket with EMan for further communication */ 
_someClearRegData ( data, env ); 

_someSetRegDataEventMask ( data, env, EMSinkEvent, NULL ); 

/* The above call enables EMan to know (during registration) that 
we are talking about a Sink Event */ 

_someSetRegDataSink ( data, env, msgsock ); 

_someSetRegDataSinkMask ( data, env, EMInputReadMask) ; 

regld = _someRegisterProc ( some_gEMan, env, data, 

ReadSocketAndPrint, " READMSG" ) ; 



someSetRegDataEventMask - Topics 



Select an item: 
Syntax 
Parameters 
Returns 
Remarks 
Original Class 
Example Code 
Related Methods 



Glossary 



someSetRegDataSink 



someSetRegDataSink - Syntax 



This method sets the file descriptor (or socket ID, or message queue ID) for the sink event. 



SOMEEMRegisterData receiver; 

Environment *env; 

long sink; 

someSetRegDataSink (receiver , env, sink); 



someSetRegDataSink Parameter - receiver 



receiver (SOMEEMRegisterData) 

A pointer to an object of class SOMEEMRegisterData. 



someSetRegDataSink Parameter - env 



env (Environment *) 

A pointer to the Environment structure for the calling method. 



someSetRegDataSink Parameter - sink 



sink (long) 

An integer value indicating the file descriptor for input/output. It can also be a socket ID, pipe ID or a message queue ID. 



someSetRegDataSink Parameter - rc 



rc 



someSetRegDataSink - Parameters 



receiver (SOMEEMRegisterData) 

A pointer to an object of class SOMEEMRegisterData. 

env (Environment *) 

A pointer to the Environment structure for the calling method, 
sink (long) 

An integer value indicating the file descriptor for input/output. It can also be a socket ID, pipe ID or a message queue ID. 



rc 



someSetRegDataSink - Remarks 



This method enables setting the true type of an event object. Typically, a subclass of Event calls this method (or overrides this method) to 
set the event type to indicate its true class(type). 



someSetRegDataSink - Original Class 

SOMEEMRegisterData 



someSetRegDataSink - Related Methods 

Methods: 

• someClearRegData 



someSetRegDataSink - Topics 



Select an item: 

Syntax 

Parameters 



Returns 
Remarks 
Original Class 
Related Methods 
Glossary 



someSetRegDataSinkMask 



someSetRegDataSinkMask - Syntax 



This method sets the sink mask within the registration data object. 



SOMEEMRegisterData receiver; 

Environment *env; 

unsigned long sinkmask; 

someSetRegDataSinkMask (receiver , env, sinkmask); 



someSetRegDataSinkMask Parameter - receiver 



receiver (SOMEEMRegisterData) 

A pointer to an object of class SOMEEMRegisterData. 



someSetRegDataSinkMask Parameter - env 



env (Environment *) 

A pointer to the Environment structure for the calling method. 



someSetRegDataSinkMask Parameter - sinkmask 



sinkmask (unsigned long) 

A bit mask indicating the types of events of interest on a given sink. 



someSetRegDataSinkMask Parameter - rc 



rc 



someSetRegDataSinkMask - Parameters 



receiver (SOMEEMRegisterData) 

A pointer to an object of class SOMEEMRegisterData. 

env (Environment *) 

A pointer to the Environment structure for the calling method, 
sinkmask (unsigned long) 

A bit mask indicating the types of events of interest on a given sink. 



rc 



someSetRegDataSinkMask - Remarks 



The sink mask within the registration data allows one to express interest in different events of the same event source. For example, using 
this mask one can express interest in being notified when there is input for reading, when the resource is ready for writing output, or just 
when exceptions occur. 



someSetRegDataSinkMask - Original Class 



SOMEEMRegisterData 



someSetRegDataSinkMask - Related Methods 



Methods: 



someSetRegDataSink 

someClearRegData 



someSetRegDataSinkMask - Example Code 




#include <eman.h> 
long regldl; 
int msgsock; 



/* Register msgsock socket with EMan for further communication */ 
_someClearRegData ( data, env ); 

_someSetRegDataEventMask ( data, env, EMSinkEvent, NULL ); 
_someSetRegDataSink ( data, env, msgsock ) ; 

_someSetRegDataSinkMask ( data, env, 

EMInputReadMask EMInputExceptMask) ; 

/* The above call expresses interest in knowing when there is 
input to be read from the socket and when there is an exception 
condition associated with this socket. */ 
regld = _someRegisterProc ( some_gEMan, env, data, 

ReadSocketAndPrint, " READMSG" ); 



someSetRegDataSinkMask - Topics 



Select an item: 
Syntax 
Parameters 
Returns 
Remarks 
Original Class 
Example Code 
Related Methods 
Glossary 



someSetRegDataTimerCount 



someSetRegDataTimerCount - Syntax 



This method sets the number of times the timer will trigger, within the registration data. 



SOMEEMRegisterData receiver; 

Environment *env; 

long count; 

someSetRegDataTimerCount (receiver, env, count) ; 



someSetRegDataTimerCount Parameter - receiver 



receiver (SOMEEMRegisterData) 

A pointer to an object of class SOMEEMRegisterData. 



someSetRegDataTimerCount Parameter - env 



env (Environment *) 

A pointer to the Environment structure for the calling method. 



someSetRegDataTimerCount Parameter - count 



count (long) 

An integer indicating the number of times the timer event has to occur. 



someSetRegDataTimerCount Parameter - rc 



rc 



someSetRegDataTimerCount - Parameters 



receiver (SOMEEMRegisterData) 

A pointer to an object of class SOMEEMRegisterData. 

env (Environment *) 

A pointer to the Environment structure for the calling method, 
count (long) 

An integer indicating the number of times the timer event has to occur. 

rc 



someSetRegDataTimerCount - Remarks 




The someSetRegDataTimerCount method sets the number of times the timer will trigger, within the registration data. The default behavior 
is for the timer to trigger indefinitely. 



someSetRegDataTimerCount - Original Class 



SOMEEMRegisterData 



someSetRegDataTimerCount - Related Methods 



Methods: 



someClearRegData 



someSetRegDataTimerCount - Example Code 



#include <eman.h> 
long regldl; 



/* Register a timer */ 

_someClearRegData ( data, env ); 

_someSetRegDataEventMask ( data, env, EMTimerEvent , NULL ); 
_someSetRegDataTimerInterval ( data, env, 100 ) ; 

_someSetRegDataTimerCount (data, env, 1) ; 

/* make this a one time timer event */ 

regldl = _someRegister ( some_gEMan, env, data, target, 

"eventMethod" , "Timer 100" ); 



someSetRegDataTimerCount - Topics 



Select an item: 
Syntax 
Parameters 
Returns 
Remarks 
Original Class 
Example Code 
Related Methods 
Glossary 



someSetRegDataTimerlnterval 



someSetRegDataTimerlnterval - Syntax 



This method sets the timer interval within the registration data. 



SOMEEMRegisterData receiver; 

Environment *env; 

long interval; 

someSetRegDataTimerlnterval (receiver, env, 
interval) ; 



someSetRegDataTimerlnterval Parameter - receiver 



receiver (SOMEEMRegisterData) 

A pointer to an object of class SOMEEMRegisterData. 



someSetRegDataTimerlnterval Parameter - env 



env (Environment *) 

A pointer to the Environment structure for the calling method. 



someSetRegDataTimerlnterval Parameter - interval 



interval (long) 

An integer indicating the timer interval in milliseconds. 



someSetRegDataTimerlnterval Parameter - rc 



rc 



someSetRegDataTimerlnterval - Parameters 



receiver (SOMEEMRegisterData) 

A pointer to an object of class SOMEEMRegisterData. 

env (Environment *) 

A pointer to the Environment structure for the calling method. 

interval (long) 

An integer indicating the timer interval in milliseconds. 



rc 



someSetRegDataTimerlnterval - Remarks 



This call allows setting the timer interval (in milliseconds) within the registration data object. 



someSetRegDataTimerlnterval - Original Class 



SOMEEMRegisterData 



someSetRegDataTimerlnterval - Related Methods 



Methods: 



someClearRegData 



someSetRegDataTimerlnterval - Example Code 



#include <eman.h> 
long regldl; 



/* Register a timer */ 

_someClearRegData ( data, env ); 

_someSetRegDataEventMask ( data, env, EMTimerEvent , NULL ); 
_someSetRegDataTimerInterval ( data, env, 100 ) ; 

/* Sets the timer interval to 100 milliseconds */ 
regldl = _someRegister ( some_gEMan, env, data, target, 

"eventMethod" , "Timer 100" ); 




someSetRegDataTimerlnterval - Topics 



Select an item: 
Syntax 
Parameters 
Returns 
Remarks 
Original Class 
Example Code 
Related Methods 
Glossary 



SOMEEvent 



File stem: event 
Base 

SOMObject 

Metaclass 

SOMCIass 

Ancestor Classes 
SOMCIass 

SOMObject 

Description 

This is the base class for all generic events within the Event Manager. It simply temestamps an event before it is passed to a callback 
routine. The event type is set to the true type by a subclass. The types currently used by the Event Management Framework are defined in 
eventmsk.h. Any subclass of this class must avoid name and value collisions with eventmsk.h. 

New methods 

The following list shows new methods defined for the SOMEEvent class. 

• somevGetEventTime 

• somevGetEventType 

• somevSetEventTime 

• somevSetEventType 

Overriding methods 

The following list shows all the methods overridden by the SOMEEvent class. These methods are overridden in order to modify the behavior 
defined by an ancestor class. 

• somlnit 



somevGetEventTime 



somevGetEventTime - Syntax 



Returns the time of the generic event in milliseconds. 



SOMEEvent receiver; 

Environment *env; 

unsigned long rc; 

rc = _somevGetEventTime (receiver, env) ; 



somevGetEventTime Parameter - receiver 



receiver (SOMEEvent) 

A pointer to an object of class SOMEEvent. 



somevGetEventTime Parameter - env 



env (Environment *) 

A pointer to the Environment structure for the calling method. 



somevGetEventTime Parameter - rc 



rc (unsigned long) 

An event timestamp in milliseconds. 



somevGetEventTime - Parameters 



receiver (SOMEEvent) 

A pointer to an object of class SOMEEvent. 

env (Environment *) 

A pointer to the Environment structure for the calling method. 

rc (unsigned long) 

An event timestamp in milliseconds. 



somevGetEventTime - Remarks 



Eman timestamps every event before dispatching it. The current time is obtained from the operating system (for example, using a 
'gettimeofday' call), is converted to milliseconds, and is given as the value of the timestamp. When this function is called, the event 
timestamp is returned. 



somevGetEventTime - Original Class 



SOMEEvent 



somevGetEventTime - Related Methods 



Methods 



somevSetEventTime 



somevGetEventTime - Topics 



Select an item: 
Syntax 
Parameters 
Returns 
Remarks 
Original Class 
Related Methods 
Glossary 



somevGetEventT ype 



somevGetEventType - Syntax 



Returns the type of the generic event. 



SOMEEvent 

Environment 



receiver; 

env; 



unsigned long rc; 

rc = _somevGetEventType (receiver, env) ; 



somevGetEventType Parameter - receiver 



receiver (SOMEEvent) 

A pointer to an object of class SOMEEvent. 



somevGetEventType Parameter - env 



env (Environment *) 

A pointer to the Environment structure for the calling method. 



somevGetEventType Parameter - rc 



rc (unsigned long) 

A type value (an integer constant defined in eventmsk.h). 



somevGetEventType - Parameters 



receiver (SOMEEvent) 

A pointer to an object of class SOMEEvent. 

env (Environment *) 

A pointer to the Environment structure for the calling method, 
rc (unsigned long) 

A type value (an integer constant defined in eventmsk.h). 



somevGetEventType - Remarks 



This method returns the true type of a given event object (for example, to identify the particular subclass of the event object). The type is an 
integer valued constant defined in eventmsk.h. 



somevGetEventType - Original Class 



SOMEEvent 



somevGetEventType - Related Methods 



Methods 



somevSetEventT ype 



somevGetEventType - Topics 



Select an item: 
Syntax 
Parameters 
Returns 
Remarks 
Original Class 
Related Methods 
Glossary 



somevSetEventTime 



somevSetEventTime - Syntax 



Sets the time of the generic event (time is in milliseconds). 



SOMEEvent receiver; 

Environment *env; 

unsigned long time; 

somevSetEventTime (receiver, env, time) ; 



somevSetEventTime Parameter - receiver 



receiver (SOMEEvent) 

A pointer to an object of class SOMEEvent. 



somevSetEventTime Parameter - env 



env (Environment *) 

A pointer to the Environment structure for the calling method. 



somevSetEventTime Parameter - time 



time (unsigned long) 



somevSetEventTime Parameter - rc 



somevSetEventTime - Parameters 



receiver (SOMEEvent) 

A pointer to an object of class SOMEEvent. 

env (Environment *) 

A pointer to the Environment structure for the calling method, 
time (unsigned long) 



rc 



somevSetEventTime - Remarks 



EMan timestamps every event before dispatching it. The current time is obtained from the operating system (for example, using a 
'gettimeofday' call), converted to milliseconds, and is given as the value of the timestamp. When an event occurs, EMan sets the timestamp 
of the event by calling this method. 




somevSetEventTime - Original Class 



SOMEEvent 



somevSetEventTime - Related Methods 



Methods 



somevGetEventTime 



somevSetEventTime - Topics 



Select an item: 
Syntax 
Parameters 
Returns 
Remarks 
Original Class 
Related Methods 
Glossary 



somevSetEventT ype 



somevSetEventType - Syntax 



Sets the type of the generic event. 



SOMEEvent receiver; 

Environment *env; 

unsigned long type; 

somevSetEventType (receiver, env, type) ; 



somevSetEventType Parameter - receiver 



receiver (SOMEEvent) 

A pointer to an object of class SOMEEvent. 



somevSetEventType Parameter - env 



env (Environment *) 

A pointer to the Environment structure for the calling method. 



somevSetEventType Parameter - type 



type (unsigned long) 

An integer value indicating the type of the event (a constant defined in eventmsk.h). 



somevSetEventType Parameter - rc 



somevSetEventType - Parameters 



receiver (SOMEEvent) 

A pointer to an object of class SOMEEvent. 

env (Environment *) 

A pointer to the Environment structure for the calling method, 
type (unsigned long) 

An integer value indicating the type of the event (a constant defined in eventmsk.h). 



rc 



somevSetEventType - Remarks 



This method enables setting the true type of an event object. Typically, a subclass of SOMEEvent calls this method (or overrides this 




method) to set the event type to indicate its true type. 



somevSetEventType - Original Class 

SOMEEvent 



somevSetEventType - Related Methods 

Methods 

• somevGetEventType 



somevSetEventType - Topics 



Select an item: 
Syntax 
Parameters 
Returns 
Remarks 
Original Class 
Related Methods 
Glossary 



SOMESinkEvent 



File stem: sinkev 
Base 

SOMEEvent 

Metaclass 

SOMCIass 

Ancestor Classes 
SOMEEvent 

SOMObject 

Description 

This class describes a sink event that is generated by EMan when it notices activity on a registered sink. On AIX, a sink refers to any file 
descriptor ( file open for reading or writing), any pipe descriptor, a socket ID or a message queue ID. On OS/2, a sink refers to a socket ID. 
One can register for three types of interest in a sink: Read interest, Write interest, and Exception interest. (See eventmsk.h file to determine 
the appropriate bit constants and see method someSetRegDataSinkMask for their use.) 

EMan passes an instance of this class as a parameter to the callback registered for Sink Events. The callback can query the instance for 
some information on the sink. 



New methods 



The following list shows all the SOMESinkEvent methods. 

• somevGetEventSink 

■ somevSetEventSink 

Overridden methods 

The following list shows all the methods overridden by the SOMESinkEvent class. These methods are overridden in order to modify the 
behavior defined by an ancestor class. 

• somlnit 



somevGetEventSink 



somevGetEventSink - Syntax 



This method returns the sink, or source of I/O, of the generic sink event. 



SOMESinkEvent receiver; 

Environment *env; 

long rc; 

rc = somevGetEventSink (receiver, env) ; 



somevGetEventSink Parameter - receiver 



receiver (SOMESinkEvent) 

A pointer to an object of class SOMESinkEvent. 



somevGetEventSink Parameter - env 



env (Environment *) 

A pointer to the Environment structure for the calling method. 



somevGetEventSink Parameter - rc 



rc (long) 

An integer value indicating the file descriptor for input/output. It can also be a socket ID, pipe ID or a message queue ID. 



somevGetEventSink - Parameters 



receiver (SOMESinkEvent) 

A pointer to an object of class SOMESinkEvent. 

env (Environment *) 

A pointer to the Environment structure for the calling method, 
rc (long) 

An integer value indicating the file descriptor for input/output. It can also be a socket ID, pipe ID or a message queue ID. 



somevGetEventSink - Remarks 



The sink ID in the SinkEvent is returned. For message queues it is the queue ID, for files it is the file descriptor, for sockets it is the socket 
ID, and for pipes it is the pipe descriptor. 



somevGetEventSink - Original Class 

SOMESinkEvent 



somevGetEventSink - Related Methods 

Methods: 

■ somevSetEventSink 



somevGetEventSink - Topics 



Select an item: 

Syntax 

Parameters 

Returns 

Remarks 

Original Class 

Related Methods 



Glossary 



somevSetEventSink 



somevSetEventSink - Syntax 



This method sets the sink, or source of I/O, of the generic sink event. 



SOMESinkEvent receiver; 

Environment *env; 

long sink; 

somevSetEventSink (receiver , env, sink); 



somevSetEventSink Parameter - receiver 



receiver (SOMESinkEvent) 

A pointer to an object of class SOMESinkEvent. 



somevSetEventSink Parameter - env 



env (Environment *) 

A pointer to the Environment structure for the calling method. 



somevSetEventSink Parameter - sink 



sink (long) 

An integer value indicating the file descriptor for input/output. It can also be a socket ID, pipe ID, or a message queue ID. 



somevSetEventSink Parameter - rc 



rc 



somevSetEventSink - Parameters 



receiver (SOMESinkEvent) 

A pointer to an object of class SOMESinkEvent. 

env (Environment *) 

A pointer to the Environment structure for the calling method, 
sink (long) 

An integer value indicating the file descriptor for input/output. It can also be a socket ID, pipe ID, or a message queue ID. 



rc 



somevSetEventSink - Remarks 



The sink ID in the SinkEvent is set. For message queues, it is the queue ID; for files it is the file descriptor; for sockets it is the socket ID; 
and for pipes it is the pipe descriptor. 



somevSetEventSink - Original Class 

SOMESinkEvent 



somevSetEventSink - Related Methods 

Methods: 

■ somevGetEventSink 



somevSetEventSink - Topics 



Select an item: 

Syntax 

Parameters 



Returns 
Remarks 
Original Class 
Related Methods 
Glossary 



SOMETimerEvent 



File stem: timerev 
Base 

SOMEEvent 

Metaclass 

SOMCIass 

Ancestor Classes 
SOMEEvent 

SOMObject 

Description 

This class describes a timer event that is generated by EMan when any of its registered timers pops. 

EMan passes an instance of this class as a parameter to the callbacks registered for Timer Events. The callback can query the instance for 
information on the timer interval and on any generic event properties. 

New methods The following list shows all the SOMETimerEvent methods. 

• somevGetEventlnterval 

• somevSetEventlnterval 

Overridden methods 

The following list shows all the methods overridden by the SOMETimerEvent class. These methods are overridden in order to modify the 
behavior defined by an ancestor class. 

• somlnit 



somevGetEventlnterval 



somevGetEventlnterval - Syntax 



This method returns the interval of the generic timer event (time in milliseconds). 



SOMETimerEvent receiver; 
Environment *env; 



somevGetEventlnterval (receiver, env) ; 



somevGetEventlnterval Parameter - receiver 



receiver (SOMETimerEvent) 

A pointer to an object of class SOMETimerEvent. 



somevGetEventlnterval Parameter - env 



env (Environment *) 

A pointer to the Environment structure for the calling method. 



somevGetEventlnterval Parameter - rc 



rc 

The interval time in milliseconds. 



somevGetEventlnterval - Parameters 



receiver (SOMETimerEvent) 

A pointer to an object of class SOMETimerEvent. 

env (Environment *) 

A pointer to the Environment structure for the calling method. 



rc 

The interval time in milliseconds. 



somevGetEventlnterval - Remarks 



The somevGetEventlnterval method returns the interval of the generic timer event (time in milliseconds). 



somevGetEventlnterval - Original Class 




SOMETimerEvent 



somevGetEventlnterval - Related Methods 



Methods 



somevSetEventlnterval 



somevGetEventlnterval - Topics 



Select an item: 
Syntax 
Parameters 
Returns 
Remarks 
Original Class 
Related Methods 
Glossary 



somevSetEventlnterval 



somevSetEventlnterval - Syntax 



This method sets the interval of the generic timer event (in milliseconds). 



SOMETimerEvent receiver; 

Environment *env; 

long interval; 

somevSetEventlnterval (receiver, env, interval) ; 



somevSetEventlnterval Parameter - receiver 



receiver (SOMETimerEvent) 

A pointer to an object of class SOMETimerEvent. 



somevSetEventlnterval Parameter - env 



env (Environment *) 

A pointer to the Environment structure for the calling method. 



somevSetEventlnterval Parameter - interval 



interval (long) 

The timer interval in milliseconds. 



somevSetEventlnterval Parameter - rc 



rc 



somevSetEventlnterval - Parameters 



receiver (SOMETimerEvent) 

A pointer to an object of class SOMETimerEvent. 

env (Environment *) 

A pointer to the Environment structure for the calling method. 

interval (long) 

The timer interval in milliseconds. 



rc 



somevSetEventlnterval - Remarks 



The somevSetEventlnterval method sets the interval of the generic timer event (in milliseconds). 



somevSetEventlnterval - Original Class 




SOMETimerEvent 



somevSetEventlnterval - Related Methods 



Methods 



somevGetEventlnterval 



somevSetEventlnterval - Topics 



Select an item: 
Syntax 
Parameters 
Returns 
Remarks 
Original Class 
Related Methods 
Glossary 



SOMEWorkProcEvent 



File stem: workprev 
Base 

SOMEEvent 

Metaclass 

SOMCIass 

Ancestor Classes 
SOMEEvent 

SOMObject 

Description 

This class describes a work procedure event object. It currently has no methods of its own. However, it sets the event type in its super class 
to say "EMWorkProcEvent" to help identify itself. These events are created and dispatched by EMan when a work procedure (something 
that the application wants to run when no other events are happening) is registered with EMan. 

EMan passes an instance of this class as a parameter to the callback registered for WorkProc Events. 

New methods 

There are currently no new methods defined for the SOMEWorkProcEvent class. 

Overridden methods 

The following list shows all the methods overridden by the SOMEWorkProcEvent class. These methods are overridden in order to modify 
the behavior defined by an ancestor class. 



somlnit 



Notices 



Second Edition (January 1996) 

The following paragraph does not apply to the United Kingdom or any country where such provisions are inconsistent with local 
law: INTERNATIONAL BUSINESS MACHINES CORPORATION PROVIDES THIS PUBLICATION "AS IS" WITHOUT WARRANTY OF 
ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY 
OR FITNESS FOR A PARTICULAR PURPOSE. Some states do not allow disclaimer of express or implied warranties in certain 
transactions, therefore, this statement may not apply to you. 

This publication could include technical inaccuracies or typographical errors. Changes are periodically made to the information herein; these 
changes will be incorporated in new editions of the publication. IBM may make improvements and/or changes in the product(s) and/or the 
program(s) described in this publication at any time. 

It is possible that this publication may contain reference to, or information about, IBM products (machines and programs), programming, or 
services that are not announced in your country. Such references or information must not be construed to mean that IBM intends to 
announce such IBM products, programming, or services in your country. 

Requests for technical information about IBM products should be made to your IBM reseller or IBM marketing representative. 



Copyright Notices 



COPYRIGHT LICENSE: This publication contains printed sample application programs in source language, which illustrate OS/2 
programming techniques. You may copy, modify, and distribute these sample programs in any form without payment to IBM, for the 
purposes of developing, using, marketing or distributing application programs conforming to the OS/2 application programming interface. 

Each copy of any portion of these sample programs or any derivative work, which is distributed to others, must include a copyright notice as 
follows: "(C) (your company name) (year). All rights reserved." 

(C) Copyright International Business Machines Corporation 1994, 1996. All rights reserved. 

Note to U.S. Government Users - Documentation related to restricted rights - Use, duplication or disclosure is subject to restrictions set forth 
in GSA ADP Schedule Contract with IBM Corp. 



Disclaimers 



References in this publication to IBM products, programs, or services do not imply that IBM intends to make these available in all countries 
in which IBM operates. Any reference to an IBM product, program, or service is not intended to state or imply that only IBM's product, 
program, or service may be used. Subject to IBM's valid intellectual property or other legally protectable rights, any functionally equivalent 
product, program, or service may be used instead of the IBM product, program, or service. Evaluation and verification of operation in 
conjunction with other products, programs, or services, except those expressly designated by IBM, are the user's responsibility. 

IBM may have patents or pending patent applications covering subject matter in this document. The furnishing of this document does not 
give you any license to these patents. You can send license inquiries, in writing, to the IBM Director of Licensing, IBM Corporation, 500 
Columbus Avenue, Thornwood, NY 10594, U.S. A. 



Trademarks 



The following terms are trademarks of the IBM Corporation in the United States or other countries or both: The following terms are 




trademarks of the International Business Machines Corporation in the United States and/or other countries 



AIX 

Operating System/2 
OS/2 

OS/2 Workplace Shell 
RISC System 6000 
SOMobjects 
System Object Model 



The following terms are trademarks of other companies: 

Each of the following terms used in this publication is a trademark of another company: 



Trademark 

EXCEL 

Intel 

IPX 

Lotus 1-2-3 
NetWare 
Objective-C 
Windows 



Owner 

Microsoft Corporation 

Intel Corporation 

Novell Corporation 

Lotus Development Corporation 

Novell Corporation 

The Stepstone Corporation 

Microsoft Corporation 




